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.0.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 RN80 "SCIP 8.0"
409 * - \subpage RN70 "SCIP 7.0"
410 * - \subpage RN60 "SCIP 6.0"
411 * - \subpage RN50 "SCIP 5.0"
412 * - \subpage RN40 "SCIP 4.0"
413 * - \subpage RN32 "SCIP 3.2"
414 * - \subpage RN31 "SCIP 3.1"
415 * - \subpage RN30 "SCIP 3.0"
416 * - \subpage RN21 "SCIP 2.1"
417 * - \subpage RN20 "SCIP 2.0"
418 * - \subpage RN12 "SCIP 1.2"
419 * - \subpage RN11 "SCIP 1.1"
420 * - \subpage RN10 "SCIP 1.0"
421 * - \subpage RN09 "SCIP 0.9"
422 * - \subpage RN08 "SCIP 0.8"
423 * - \subpage RN07 "SCIP 0.7"
424 *
425 */
426
427/**@page WHATPROBLEMS What types of optimization problems does SCIP solve?
428 *
429 * As a stand-alone solver, \SCIP can solve mixed-integer nonlinear programs \b (MINLPs), to which it applies
430 * an LP based spatial branch-and-cut algorithm. This method is guaranteed to solve bounded MINLPs
431 * within a given numerical tolerance in a finite amount of time. In particular, \SCIP is a stand-alone
432 * solver for mixed-integer linear programs \b (MIPs).
433 *
434 * As a framework, \SCIP also provides the tools to solve constraint optimization problems defined over
435 * integer and continuous variables. Therefore, the design of \SCIP
436 * supports the easy integration of constraints of arbitrary type into the solver.
437 * More precisely, \SCIP can handle the class of constraint integer programs \b (CIPs), which are constraint optimization problems
438 * that become linear programs (LPs) after the integer variables are fixed.
439 *
440 * @section PROBLEMCLASSES Some important subclasses of CIP and MINLP
441 *
442 * The following table gives a non-exhaustive list of common types of mathematical optimization problems that can be solved
443 * through \SCIP itself or one of its extensions. Some recommendations are given on how to compile \SCIP for a
444 * certain problem class and how make best use of \SCIP. The file format column gives some common file
445 * formats for every class. Note that since some of the mentioned problem classes are more general than others (like
446 * every LP is a MIP is an MINLP), the formats for the superclass should always work just as fine, although they
447 * may be less common for the class at hand.
448 *
449 * Please see also the pages on \ref EXAMPLES "SCIP Examples" and \ref APPLICATIONS "SCIP Applications" to learn more on how
450 * to extend \SCIP for a particular MIP, MINLP, or CIP application.
451 * All examples and applications use the C or C++ APIs of \SCIP. Please have a look at \ref INTERFACES "SCIP interfaces"
452 * to see how to use \SCIP from within other programming languages.
453 *
454 * <table class="types">
455 * <caption align="top">Some problem classes that can be solved by \SCIP</caption>
456 * <tr style="border-bottom: medium solid black;">
457 * <th>Problem class</th>
458 * <th>Mathematical problem description</th>
459 * <th>Supported file formats</th>
460 * <th>Recommendations</th>
461 * </tr>
462 * <tr>
463 * <td>Mixed-integer linear program (MIP)</td>
464 * <td>\f{align*}{
465 * \text{min} \quad& c^T x \\
466 * \text{s.t.} \quad& Ax \geq b \\
467 * &l_{j} \leq x_{j} \leq u_{j} && \forall j \in \mathcal{N} \\
468 * &x_{j} \in \mathbb{Z} && \forall j \in \mathcal{I}
469 * \f}
470 * </td>
471 * <td>
472 * <ul>
473 * <li>\ref reader_cip.h "CIP"</li>
474 * <li>\ref reader_mps.h "MPS"</li>
475 * <li>\ref reader_lp.h "LP"</li>
476 * <li>\ref reader_zpl.h "ZPL"</li>
477 * </ul>
478 * </td>
479 * <td>
480 * <ul>
481 * <li>\SCIP requires an external LP solver to solve LP relaxations, which needs to be specified
482 * at compilation time. By default, it uses SoPlex (<code>LPS=spx</code>). See \ref MAKE for a
483 * list of available LP solver interfaces and how to use them inside \SCIP.</li>
484 * <li>Compile with Zimpl support (<code>ZIMPL=true</code>) to read in Zimpl models directly.</li>
485 * <li>\SCIP comes with many different parameters. Use the provided emphasis settings (see \ref SHELL "this tutorial")
486 * to change many parameters at once and boost the performance.</li>
487 * <li>Test instances are available at <code>check/instances/MIP/</code>.</li>
488 * </ul>
489 * </td>
490 * </tr>
491 * <tr>
492 * <td>Mixed-integer nonlinear program (MINLP)</td>
493 * <td>\f{align*}{
494 * \text{min} \quad& f(x) \\
495 * \text{s.t.} \quad& g_{i}(x) \leq 0 && \forall i \in \mathcal{M} \\
496 * &l_{j} \leq x_{j} \leq u_{j} && \forall j \in \mathcal{N} \\
497 * &x_{j} \in \mathbb{Z} && \forall j \in \mathcal{I}
498 * \f}
499 * </td>
500 * <td>
501 * <ul>
502 * <li>\ref reader_cip.h "CIP"</li>
503 * <li>\ref reader_gms.h "GMS"</li>
504 * <li>\ref reader_osil.h "OSiL"</li>
505 * <li>\ref reader_pip.h "PIP"</li>
506 * <li>\ref reader_zpl.h "ZPL"</li>
507 * <li>For MIQCPS:
508 * <ul>
509 * <li>\ref reader_lp.h "LP"</li>
510 * <li>\ref reader_mps.h "MPS"</li>
511 * </ul>
512 * </li>
513 * </ul>
514 * </td>
515 * <td>
516 * <ul>
517 * <li>Compile with <code>IPOPT=true</code> for better performance.</li>
518 * <li>Compile with <code>WORHP=true</code> for better performance.</li>
519 * <li>Compile with <code>FILTERSQP=true</code> for better performance.</li>
520 * <li>See <a href="FAQ\FILEEXT#minlptypes"> Which kind of MINLPs are supported by \SCIP? </a> in the FAQ.</li>
521 * <li>There is an interface for the modelling language AMPL, see \ref INTERFACES.</li>
522 * <li>Mixed-integer quadratically constrained programs (MIQCP) can also be formulated in the file formats
523 * <ul>
524 * <li>\ref reader_lp.h "LP", and</li>
525 * <li>\ref reader_mps.h "MPS".</li>
526 * </ul>
527 * </li>
528 * <li>Test instances are available at <code>check/instances/MINLP/</code>.</li>
529 * </ul>
530 * </td>
531 * </td>
532 * <tr>
533 * <td>Constraint Integer Program (CIP)</td>
534 * <td>\f{align*}{
535 * \text{min} \quad& c^T x + d^T y \\
536 * \text{s.t.} \quad& C_i(x,y) = \text{true} && \forall i \in \mathcal{M} \\
537 * & x \in \mathbb{Z}^{p}, y \in \mathbb{R}^{n - p}
538 * \f}
539 * 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.
540 * </td>
541 * <td>
542 * <ul>
543 * <li>\ref reader_cip.h "CIP"</li>
544 * <li>\ref reader_fzn.h "FlatZinc"</li>
545 * </ul>
546 * </td>
547 * <td>
548 * <ul>
549 * <li>\SCIP supports a limited number of general constraints; see \ref CONS "How to add constraint handlers"
550 * to learn how to extend the \SCIP framework to a given CIP.</li>
551 * <li>Use the emphasis setting <code>set emphasis cpsolver</code> to completely disable LP solves and
552 * use depth-first search with periodic restarts, see also
553 * <a href="FAQ\FILEEXT#scipascpsolver"> Can I use \SCIP as a pure CP solver? </a> in the FAQ.</li>
554 * <li>Test instances are available at <code>check/instances/CP</code>.</li>
555 * </ul>
556 * </td>
557 * <tr>
558 * <td>Convex MINLP</td>
559 * <td>Like MINLP, \f$f\f$ and all \f$g_i\f$ are \b convex.</td>
560 * <td>see MINLP formats</td>
561 * <td>
562 * <ul>
563 * <li>See the comments for MINLP.</li>
564 * <li>In addition, use <code>constraints/nonlinear/assumeconvex = TRUE</code> to inform \SCIP about a convex
565 * problem in cases where the automated detection is not strong enough.</li>
566 * <li>Test instances are available at <code>check/instances/MINLP/circle.lp</code>.</li>
567 * </ul>
568 * </td>
569 * </td>
570 * <tr>
571 * <td>Linear program (LP)</td>
572 * <td>\f{align*}{
573 * \text{min} \quad& c^T x \\
574 * \text{s.t.} \quad& Ax \geq b \\
575 * & x_{j} \geq 0 && \forall j \in \mathcal{N}
576 * \f}
577 * </td>
578 * <td>see MIP formats</td>
579 * <td>See <a href="FAQ\FILEEXT#scipaslpsolver">Can I use \SCIP as a pure LP solver</a> in the FAQ.</td>
580 * </td>
581 * <tr>
582 * <td>Pseudoboolean optimization</td>
583 * <td>\f{align*}{
584 * \text{min} \quad& c^T x \\
585 * \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} \\
586 * &x_{j} \in \{0,1\} && \forall j \in \mathcal{N}
587 * \f}
588 * </td>
589 * <td>
590 * <ul>
591 * <li>\ref reader_wbo.h "WBO"</li>
592 * <li>\ref reader_opb.h "OPB"</li>
593 * </ul>
594 * </td>
595 * <td>
596 * <ul>
597 * <li>Test instances are available at <code>check/instances/PseudoBoolean/</code>.</li>
598 * </ul>
599 * </td>
600 * </tr>
601 * <tr>
602 * <td>Satisfiability (SAT) and variants</td>
603 * <td>\f{align*}{
604 * \text{min} \quad& 0 \\
605 * \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}\\
606 * &x_{j} \in \{\text{false},\text{true}\} && \forall j \in \mathcal{N}
607 * \f}
608 * </td>
609 * <td>
610 * <ul>
611 * <li>\ref reader_cnf.h "CNF"</li>
612 * </ul>
613 * </td>
614 * <td>
615 * <ul>
616 * <li>Use the emphasis setting <code>set emphasis cpsolver</code> to completely disable LP solves and
617 * use depth-first search with periodic restarts, see also
618 * <a href="FAQ\FILEEXT#scipascpsolver"> Can I use \SCIP as a pure CP/SAT solver? </a> in the FAQ.</li>
619 * <li>Test instances are available at <code>check/instances/SAT/</code>.</li>
620 * </ul>
621 * </td>
622 * </tr>
623 * <tr>
624 * <td>Multicriteria optimization</td>
625 * <td>\f{align*}{
626 * \text{min} \quad &(c_1^T x,\ldots,c_k^T x) \\
627 * \text{s.t. } \quad& Ax \geq b \\
628 * &x \in \mathbb{K}^n
629 * \f}
630 * where \f$\mathbb{K}\f$ is either \f$\mathbb{Z}\f$ or \f$\mathbb{R}\f$.
631 * </td>
632 * <td colspan="3"> see the <a href="http://polyscip.zib.de/">PolySCIP web page</a></td>
633 * </tr>
634 * <tr>
635 * <td>Mixed-integer semidefinite program (MISDP)</td>
636 * <td>\f{align*}{
637 * \text{inf} \quad \thinspace & b^T y \\
638 * \text{s.t.} \quad & \sum_{j=1}^m A_j\, y_j - A_0 \succeq 0 \\
639 * & y_j \in \mathbb{Z} && \forall\, j \in \mathcal{I}
640 * \f}
641 * </td>
642 * <td colspan="3"> see the <a href="http://www.opt.tu-darmstadt.de/scipsdp/">SCIP-SDP web page</a></td>
643 * </tr>
644 * </table>
645 *
646 *
647 */
648
649/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
650
651/**@page CODE Coding style guidelines
652 *
653 * We follow the following coding style guidelines and recommend them for all developers.
654 *
655 * @section CODESPACING Spacing:
656 *
657 * - Indentation is 3 spaces. No tabs anywhere in the code.
658 * - Every opening parenthesis requires an additional indentation of 3 spaces.
659 *
660 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleParenIndent}
661 *
662 * - Spaces around all operators.
663 * - Spaces around the arguments inside an if/for/while-statement, as well as inside macros (e.g., SCIP_CALL).
664 * - No spaces between control structure keywords like "if", "for", "while", "switch" and the corresponding brackets.
665 * - No spaces between a function name and the parenthesis in both the definition and function calls.
666 * - Braces are on a new line and not indented.
667 * - Braces in if/for-statements should only be omitted if they enclose a single line.
668 *
669 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleIfFor}
670 *
671 * - In function declarations, every parameter is on a new line. The name of the parameter starts at column 26,
672 * the comment starts at column 46 (if column-count starts with 1).
673 * - Maximal line length is 120 characters.
674 * - Always only one declaration in a line.
675 * - Variable names should be all lower case.
676 *
677 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleDeclaration}
678 *
679 * - Blank lines are inserted where it improves readability.
680 * - Multiple blank lines are used to structure the code where single blank lines are insufficient,
681 * e.g., between differrent sections of the code.
682 *
683 * @refsnippet{src/scip/heur_xyz.c,SnippetCodeStyleBlanks}
684 *
685 * @section CODENAMING Naming:
686 *
687 * - Use assert() to show preconditions for the parameters, invariants, and postconditions.
688 * - Make all functions that are not used outside the module 'static'.
689 * - Naming should start with a lower case letter.
690 *
691 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleStaticAsserts}
692 *
693 * - All global functions start with "SCIP". In the usual naming scheme this is followed by the object and a method name
694 * like in SCIPlpAddRow(). Functions return TRUE or FALSE should be named like SCIPisFeasEQ().
695 *
696 * @refsnippet{src/scip/scip_numerics.h,SnippetCodeStyleNaming}
697 *
698 * - For each structure there is a typedef with the name in all upper case.
699 * - Defines should be named all upper case.
700 *
701 * @refsnippet{src/scip/type_set.h,SnippetCodeStyleExample}
702 *
703 * @section CODEDOC Documentation:
704 *
705 * - Document functions, parameters, and variables in a doxygen conformed way.
706 * - Please do not leave code in comments that has been commented out, don't use `#if
707 * 0`. Instead put the code within defines `#ifdef SCIP_DISABLED_CODE` and add an explanation.
708 * - Todos need double stars to be registered by doxygen.
709 * - When documenting methods, the first brief description starts with lower case and is separated by semi-colons, if necessary
710 * The longer description starts capitalized and consists of complete sentences.
711 * If the documentation consists of multiple lines, the comment end must be on a new line.
712 *
713 * @refsnippet{src/scip/scip_datastructures.h,SnippetCodeStyleComment}
714 *
715 *
716 * @section XEMACS Customize (x)emacs
717 *
718 * If you are using (x)emacs, you can use the following customization for the c++-mode. These settings satisfy the
719 * coding guidelines of \SCIP.
720 *
721 * \include codestyle/emacs_scip_codestyle.el
722 *
723 *
724 * @section ECLIPSE Customize eclipse
725 *
726 * Eclipse user can use the profile below. This profile does not match the \SCIP coding guideline completely.
727 *
728 * \include codestyle/eclipse_scip_codestyle.xml
729 */
730
731/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
732
733/**@page START How to start a new project
734 *
735 * Once you succeeded installing \SCIP together with an LP-solver on your system,
736 * you have a powerful tool for solving MIPs, MIQCPs,
737 * MINLPs, etc... at hand. \SCIP can also be customized to the type of problems you
738 * are working on by additional plugins.
739 * Instructions on how to write a new plugin and include it in \SCIP can be found in the corresponding
740 * \ref HOWTOADD "How to add ... pages".
741 *
742 * \SCIP can also be used for writing your own branch-and-cut or branch-and-cut-and-price code. \SCIP already
743 * provides a number of existing code examples which we suggest as both reference and starting point
744 * for these kinds of projects.
745 * Below, you find some hints of how to start such a project.
746 *
747 * @section START_CHOICE Choose an example project
748 *
749 * The example should be chosen depending on the programming language (<b>C</b> or <b>C++</b>) and the purpose
750 * (<b>branch-and-cut</b> or <b>branch-and-cut-and-price</b>) of your project.
751 * <br>
752 * We suggest the use of one of the following examples:
753 * - The \ref VRP_MAIN "Vehicle Routing Problem Example" is a <b>branch-and-cut-and-price</b> (column generation)-code
754 * in <b>C++</b>.
755 * - The \ref BINPACKING_MAIN "Binpacking Example"
756 * and the \ref COLORING_MAIN "Coloring application" are
757 * <b>branch-and-cut-and-price</b> (column generation)-codes in <b>C</b>.
758 * - The \ref TSP_MAIN "TSP example"
759 * is a <b>branch-and-cut</b>-code in <b>C++</b>.
760 * - The \ref LOP_MAIN "LOP example"
761 * is a <b>branch-and-cut</b>-code in <b>C</b>.
762 *
763 * More examples can be found in the \ref EXAMPLES "list of Examples".
764 *
765 * - Copy one of the examples in the <code>examples</code> directory (in the \SCIP root
766 * directory). For instance, type
767 * \verbatim
768 cp -r examples/Binpacking/ ../SCIPProject/ ; cd ../SCIPProject
769 \endverbatim
770 * from the \SCIP root directory for copying the content of the <code>Binpacking</code>-example into a fresh
771 * directory named SCIPProject in the parent directory of the \SCIP root directory and jumping to
772 * the new SCIPProject directory rightafter.
773 *
774 * @section START_CMAKE Building with CMake
775 *
776 * It is recommended for all new users to use the CMake build system configuration, if available on their platform.
777 *
778 * - Open the <code>CMakeLists</code> (some examples projects have a subdirectory "check" for testing) via
779 * \verbatim
780 kate CMakeLists.txt & kate check/CMakeLists.txt # if check/CMakeLists.txt is available
781 \endverbatim
782 * and replace all instances of the copied project's name (e.g. <code>binpacking</code>) with your project name.
783 * - Create a new subdirectory, jump to the new directory and use cmake specifying your \SCIP directory. For instance, type
784 * \verbatim
785 mkdir Release ; cd Release ; cmake .. -DSCIP_DIR=../scip/Release
786 \endverbatim
787 * 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.
788 *
789 *
790 * @section START_MAKE Building with the Makefile system
791 *
792 * If CMake should be unavailable on your targeted platform, try the classic Makefile system of SCIP.
793 *
794 * - Open the <code>Makefile</code> via
795 * \verbatim
796 kate Makefile
797 \endverbatim
798 * and edit the following variables at the top to have a compilable code:
799 *
800 * - specify a correct path to the \SCIP root (<code>SCIPDIR</code>)
801 * - rename the targets name (<code>MAINNAME</code>)
802 * - adjust the source file names (<code>MAINOBJ</code>).
803 * .
804 * - Once you have edited the makefile, you can use all the flags that can be used in \SCIP to
805 * compile your code, see \ref MAKE.
806 *
807 */
808
809/**@page EXAMPLES Example projects
810 *
811 * \SCIP contains several examples that demonstrate its usage. They are contained in the &quot;examples&quot; directory
812 * in the source code distribution.
813 *
814 * <table>
815 * <tr>
816 * <td colspan="2">
817 * <b>
818 * Callable library
819 * </b>
820 * </td>
821 * </tr>
822 * <tr>
823 * <td>
824 * @subpage CALLABLELIBRARY_MAIN "Callable Library Example"
825 * </td>
826 * <td>
827 * An example showing how to setup constraints (esp. nonlinear ones) when using \SCIP as callable library.
828 * </td>
829 * </tr>
830 * <tr>
831 * <td>
832 * @subpage MIPSOLVER_MAIN "MIP solver"
833 * </td>
834 * <td>
835 * A minimal implementation for using \SCIP included into another source code
836 * </td>
837 * </tr>
838 * <tr>
839 * <td>
840 * @subpage QUEENS_MAIN "The n-Queens Problem"
841 * </td>
842 * <td>
843 * Using SCIP's callable library for solving the n-queens problem.
844 * </td>
845 * </tr>
846 * <tr>
847 * <td colspan="2">
848 * <b>
849 * Extending SCIP by custom plugins
850 * </b>
851 * </td>
852 * </tr>
853 * <tr>
854 * <td>
855 * @subpage EVENTHDLR_MAIN "Event handler"
856 * </td>
857 * <td>
858 * A small example illustrating the use of an event handler.
859 * </td>
860 * </tr>
861 * <tr>
862 * <td>
863 * @subpage GMI_MAIN "Gomory mixed integer cut example"
864 * </td>
865 * <td>
866 * An example about Gomory mixed-integer cuts.
867 * </td>
868 * </tr>
869 * <tr>
870 * <td>
871 * @subpage RELAXATOR_MAIN "Relaxator example"
872 * </td>
873 * <td>
874 * An example about using custom relaxators.
875 * </td>
876 * </tr>
877 * <tr>
878 * <td colspan="2">
879 * <b>
880 * Branch-and-cut
881 * </b>
882 * </td>
883 * </tr>
884 * <tr>
885 * <td>
886 * @subpage SUDOKU_MAIN "Sudoku example"
887 * </td>
888 * <td>
889 * An example solving sudokus.
890 * </td>
891 * </tr>
892 * <tr>
893 * <td>
894 * @subpage LOP_MAIN "Linear Ordering"
895 * </td>
896 * <td>
897 * An example for implementing a constraint handler.
898 * </td>
899 * </tr>
900 * <tr>
901 * <td>
902 * @subpage TSP_MAIN "The TSP example"
903 * </td>
904 * <td>
905 * A short implementations of a constraint handler, two easy combinatorial heuristics, a file reader, etc. which
906 * demonstrate the usage of \SCIP as a branch-and-cut-framework for solving traveling salesman problem instances.
907 * </td>
908 * </tr>
909 * <tr>
910 * <td colspan="2">
911 * <b>
912 * Branch-and-price
913 * </b>
914 * </td>
915 * </tr>
916 * <tr>
917 * <td>
918 * @subpage BINPACKING_MAIN "Binpacking"
919 * </td>
920 * <td>
921 * An implementation of the column generation approach for the binpacking problem. It includes a customized reader,
922 * Ryan/Foster branching rule, (global) problem data, variable data, and constraint handler.
923 * </td>
924 * </tr>
925 * <tr>
926 * <td>
927 * @subpage VRP_MAIN "Vehicle Routing"
928 * </td>
929 * <td>
930 * A solver for a simple capacity-constrained vehicle routing problem, which is based on pricing tours via a dynamic
931 * programming algorithm.
932 * </td>
933 * </tr>
934 * <tr>
935 * <td colspan="2">
936 * <b>
937 * Benders' decomposition
938 * </b>
939 * </td>
940 * </tr>
941 * <tr>
942 * <td>
943 * @subpage SCFLP_MAIN "Stochastic capacitated facility location problem"
944 * </td>
945 * <td>
946 * A stochastic programming problem that demonstrates the use of the Benders' decomposition framework within SCIP.
947 * </td>
948 * </tr>
949 * </table>
950 */
951
952/** @page APPLICATIONS Application projects
953 *
954 * There are several extensions of \SCIP for particular applications included in the release. They are contained in the &quot;applications&quot; directory
955 * in the source code distribution.
956 *
957 * <table>
958 * <tr>
959 * <td>
960 * @subpage COLORING_MAIN
961 * </td>
962 * <td>
963 * An implementation of the column generation approach for graph coloring of Mehrotra and Trick.
964 * </td>
965 * </tr>
966 * <tr>
967 * <td>
968 * @subpage CYCLECLUSTERING_MAIN
969 * </td>
970 * <td>
971 * Branch-and-cut implementation of a graph partitioning problem used for Markov state models.
972 * </td>
973 * </tr>
974 * <tr>
975 * <td>
976 * @subpage MINIISC_MAIN
977 * </td>
978 * <td>
979 * A solver that computes irreducible infeasible subsystems using Benders decomposition
980 * </td>
981 * </tr>
982 * <tr>
983 * <td>
984 * @subpage POLYSCIP_MAIN
985 * </td>
986 * <td>
987 * A solver for multi-objective optimization problems.
988 * </td>
989 * </tr>
990 * <tr>
991 * <td>
992 * @subpage RINGPACKING_MAIN "Ringpacking"
993 * </td>
994 * <td>
995 * An implementation of the column generation approach for the Ringpacking Problem. It includes a customized reader,
996 * (global) problem data, variable data, and constraint handler.
997 * </td>
998 * </tr>
999 * <tr>
1000 * <td>
1001 * @subpage SCHEDULER_MAIN
1002 * </td>
1003 * <td>
1004 * A solver for scheduling problems.
1005 * </td>
1006 * </tr>
1007 * </table>
1008 *
1009 */
1010
1011
1012/**@page SHELL Tutorial: the interactive shell
1013 *
1014 * If you are using \SCIP as a black box solver, here you will find some tips and tricks what you can do.
1015 *
1016 * @section TUTORIAL_OPTIMIZE Read and optimize a problem instance
1017 *
1018 * @subsection SHELL_PREREQUISITES "Prerequisites"
1019 *
1020 * First of all, we need a \SCIP binary and an example problem file to work with.
1021 * For installation we refer you to the \ref INSTALL section.
1022 *
1023 * Therefore, you can either download the \SCIP standard distribution (which includes problem files) and compile it on your own or you can download a
1024 * precompiled binary and an example problem separately. \SCIP can read files in LP, MPS, ZPL, WBO, FZN, PIP, OSiL, and
1025 * other formats (see \ref FILEREADERS).
1026 *
1027 * If you want to download the source code of the \SCIP standard distribution, we recommend to go to the <a
1028 * href="https://scipopt.org/#download">SCIP download section</a>, download the latest release,
1029 * inflate the tarball (e.g., with "tar xzf scipoptsuite-[version].tgz"), and follow the instructions
1030 * in the INSTALL file. The instance stein27, which will serve as an example in this tutorial, can be found under
1031 * scipoptsuite-[version]/scip-[version]/check/instances/MIP/stein27.fzn.
1032 * Alternatively you can download an instance file from the <a href="https://miplib.zib.de/tag_benchmark.html">MIPLIB 2017 page</a>.
1033 *
1034 * If you want to download a precompiled binary, go to the <a href="http://scipopt.org/#download">SCIP download
1035 * section</a> and download an appropriate binary for your operating system. The \SCIP source code distribution already comes with
1036 * the example instance used throughout this tutorial. To follow this tutorial with a precompiled binary, we recommend downloading the instance
1037 * <a href="http://miplib2010.zib.de/miplib3/miplib3/stein27.mps.gz">stein27</a> from
1038 * the <a href="http://miplib2010.zib.de/miplib3/miplib.html">MIPLIB 3.0</a> homepage.
1039 *
1040 * @subsection SHELL_AFTERINSTALL "After installation"
1041 *
1042 * Now start your binary, without any arguments. This opens the interactive shell, which should look somehow like this:
1043 *
1044 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetVersion
1045 *
1046 * First of all "help" shows you a list of all available shell commands. Brackets indicate a submenu with further options.
1047 *
1048 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetHelp
1049 *
1050 * 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
1051 * solution" to show the nonzero variables of the best found solution.
1052 *
1053 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetOpt1
1054 *
1055 * What do we see here? After "optimize", SCIP first goes into presolving. Not much is happening for this instance, just
1056 * the linear constraints get upgraded to more specific types. Each round of presolving will be displayed in a single
1057 * line, with a short summary at the end. Then, we see the actual solving process. The table output of the branch-and-cut
1058 * solving process is very detailed during the root node. Afterwards, a new line is displayed every 100th node.
1059 * Furthermore, every new incumbent solution triggers a new table row, starting with a character to indicate the
1060 * heuristic that found the solution. Which letter represents which heuristic can be seen with the
1061 * "display heuristics" command, see \ref TUTORIAL_STATISTICS for an example.
1062 *
1063 * After some lines the root node processing is finished. From now on, we will see an output line every hundredth node or
1064 * whenever a new incumbent is found. After some more nodes, the "dualbound" starts
1065 * moving, too. At one point, both will be the same, and the solving process terminates, showing us some wrap-up
1066 * information.
1067 *
1068 * The exact performance may of course vary among different architectures and operating systems. Do not be worried if
1069 * your installation needs more or less time or nodes to solve. Also, this instance has more than 2000 different optimal
1070 * solutions. The optimal objective value always has to be 18, but the solution vector may differ. If you are interested
1071 * in this behavior, which is called "performance variability", you may have a look at the MIPLIB2010 paper.
1072 *
1073 * @section TUTORIAL_FILEIO Writing problems and solutions to a file
1074
1075 * \SCIP can also write information to files. E.g., we could store the incumbent solution to a file, or output the
1076 * problem instance in another file format (the LP format is much more human readable than the MPS format, for example).
1077 *
1078 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetWriteSolutions
1079 *
1080 * Passing starting solutions can increase the solving performance so that \SCIP does not need to construct an initial feasible solution
1081 * by itself. After reading the problem instance, use the "read" command again, this time with a file containing solution information.
1082 * Solutions can be specified in a raw or xml-format and must have the file extension ".sol", see the documentation of the
1083 * \ref reader_sol.h "solution reader of SCIP" for further information.
1084 *
1085 * Customized settings are not written or read with the "write" and "read" commands, but with the three commands
1086 *
1087 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSaveSettingsOverview
1088 *
1089 * See the section on parameters \ref TUTORIAL_PARAMETERS for more information.
1090 *
1091 * @section TUTORIAL_STATISTICS Displaying detailed solving statistics
1092 *
1093 * We might want to have some more information now. Which of the heuristics found solutions? Which plugins
1094 * were called during the solutions process and how much time did they spend?
1095 * Information on certain plugin types (e.g., heuristics, branching rules, separators) is displayed via
1096 * "display <plugin-type>", information on the solution process via "display statistics", and "display problem"
1097 * shows the current instance.
1098 *
1099 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetDisplayStatistics
1100 *
1101 * The statistics obtained via "display statistics" are quite comprehensive,
1102 * thus, we just explain a few lines here. Information is grouped by the plugin type. For the primal heuristics,
1103 * the execution time in seconds is shown as well as the number of calls to the heuristic, and its success regarding
1104 * the number of (best) solutions found by that heuristic. Appropriate statistics are also shown for presolvers, constraint handlers,
1105 * separators, propagators, the search tree, etc. User-written plugins will appear automatically in these statistics,
1106 * after they were included into \SCIP.
1107 *
1108 * @section TUTORIAL_PARAMETERS Changing parameters from the interactive shell
1109 *
1110 * Now, we can start playing around with parameters. The primal heuristics Rounding and shifting seem to be quite successful on this instance,
1111 * wondering what happens if we disable them? Or what happens, if we are even more rigorous and disable all heuristics?
1112 * Or if we do the opposite and use aggressive heuristics?
1113 *
1114 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSetSettings
1115 *
1116 * We can navigate through the menus step-by-step and get a list of available options and submenus. Therefore, we select
1117 * "set" to change settings, "heuristics" to change settings of primal heuristics, and "shifting" for that particular
1118 * heuristic. Then we see a list of parameters (and yet another submenu for advanced parameters), and disable this
1119 * heuristic by setting its calling frequency to -1. If we already know the path to a certain setting, we can directly
1120 * type it (as for the rounding heuristic in the above example). Note that we do not have to use the full names, but we
1121 * may use short versions, as long as they are unique.
1122 *
1123 * To solve a problem a second time, we have to read it in again before starting the optimization process.
1124 *
1125 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetOpt2
1126 *
1127 * Okay, what happened here? First, we reset all parameters to their default values, using "set default". Next, we
1128 * loaded some meta-parameter settings (also see <a href="FAQ.php#howtochangebehaviour">the FAQ</a>), to apply primal heuristics
1129 * more aggressively. \SCIP shows us, which single parameters it changed therefore. Additionally, for pedagogical purposes,
1130 * we set the node limit to 200. Now, the optimal solution is already found at the root node, by a heuristic which is
1131 * deactivated by default. Then, after node 200, the user defined node limit is reached which interrupts the solving
1132 * process, We see that now in the short status report, primal and dual bound are different, thus, the problem is not solved
1133 * yet. Nevertheless, we could access statistics, see the current incumbent solution, change parameters and so on.
1134 * Entering "optimize" we continue the solving process from the point on at which it has been interrupted.
1135 *
1136 * Once you found a non-default parameter setting that you wish to save and use in the future, use either the command
1137 *
1138 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSaveSettingsFull
1139 *
1140 * to save <b>all</b> parameter values to the specified file, or
1141 *
1142 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSaveSettingsDiff
1143 *
1144 * in order to save only the nondefault parameters. The latter has several advantages, you can, e.g., combine parameter
1145 * settings from multiple settings files stored by the latter command, as long as they only affect mutually exclusive
1146 * parameter values.
1147 *
1148 * For loading a previously stored settings file, use the "load" command:
1149 *
1150 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetLoadSettings
1151 *
1152 * Special attention should be drawn to the reserved settings file name "scip.set"; whenever the \SCIP interactive shell
1153 * is started from a working directory that contains a settings file with the name "scip.set", it will be automatically
1154 * replace the default settings.
1155 *
1156 * For using special settings for automated tests as described in \ref TEST, save your custom settings in a subdirectory
1157 * "SCIP_HOME/settings".
1158 *
1159 *
1160 * We hope this tutorial gave you an overview of what is possible using the \SCIP interactive shell. Please also read our
1161 * \ref FAQ, in particular the section "Using SCIP as a standalone MIP/MINLP-Solver".
1162 *
1163 */
1164
1165/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
1166
1167/**@page DOC How to search the documentation and source files structure for public interface methods
1168 *
1169 * 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.
1170 * - It contains interface methods for all SCIP structs, both in the solver core or in one of the plugins.
1171 * - Plugins are mostly independent from each other, so to use them it is usually enough to browse the \ref PUBLICCOREAPI "Core API".
1172 * - If you want to add your own plugins, see the \ref HOWTOADD pages for exhaustive information for each plugin type.
1173 * - If you are learning SCIP with a concrete project in mind, looking at the available \ref EXAMPLES page may help you
1174 * getting started.
1175 * - See also \ref START "How to start a new project"
1176 *
1177 * 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_",
1178 * such as \ref type_var.h , which contains enums and type definitions related to \ref PublicVariableMethods "SCIP problem variables".
1179 * Definitions of the actual structs can be found in separate header files starting with "struct_".
1180 * All method definitions of the public SCIP API are split across header files starting with "pub_" such as \ref pub_cons.h
1181 * or headers starting with "scip_" such as \ref scip_cons.h .
1182 * The latter headers starting with "scip_" contain more complex methods, which always receive a scip pointer as first argument.
1183 * Those methods may affect several individual components controlled by SCIP. Such a method is SCIPbranchVar(), which
1184 * affects the search tree, which is controlled by SCIP itself and not meant to be accessed by user plugins.
1185 *
1186 * It should be sufficient to include scip/scip.h and scip/scipdefplugins.h for having all
1187 * needed functionality available in a project.
1188 *
1189 * If, for example, you are looking for information on how to create a problem instance, here are some steps you can take:
1190 *
1191 * 1. Browse the SCIP Core API and follow the path \ref PUBLICAPI > \ref PUBLICCOREAPI > \ref PublicProblemMethods > \ref GlobalProblemMethods > SCIPcreateProb()
1192 * 2. Here you can find information on the function's return value, preconditions, postconditions, parameters, as well as related functions.
1193 * 3. If you are unsure of how to use some of the parameters, it is worth looking for a basic version of the function.
1194 * 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
1195 * 'References' and 'Referenced by' section of the function documentation. In this case, you can find `SCIPcreateProbBasic()`.
1196 *
1197 * The opposite case is that you already know the name of a function as, e.g., SCIPbranchVar().
1198 *
1199 * 1. Type the name of the function into the search bar to find the function documentation.
1200 * 2. In addition, you can find related methods by browsing the neighboring functions of the same group.
1201 * 3. In this example, you may now learn about SCIPgetNLPBranchCands() to query all integer
1202 * variables with fractional LP solution value, which are good candidates for classical branching on variables.
1203 *
1204 * Note that the \ref INTERNALAPI "private SCIP API" contains more complex functions and data structures that fill specialized roles and
1205 * is only for developers.
1206 * Those functions are **not** exported to the library and are therefore **not available in user projects** using the \ref PUBLICAPI "public SCIP API".
1207 */
1208
1209/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
1210
1211/**@page CONS How to add constraint handlers
1212 *
1213 * A constraint handler defines the semantics and the algorithms to process constraints of a certain class. A single
1214 * constraint handler is responsible for all constraints belonging to its constraint class. For example, there is
1215 * one \ref cons_knapsack.h "knapsack constraint handler" that ensures solutions are only accepted if they satisfy all
1216 * knapsack constraints in the model. \n A complete list of all constraint handlers contained in this release can be
1217 * found \ref CONSHDLRS "here".
1218 *
1219 * We now explain how users can add their own constraint handlers.
1220 * For an example, look into the subtour constraint handler (examples/TSP/src/ConshdlrSubtour.cpp) of the
1221 * \ref TSP_MAIN project.
1222 * The example is written in C++ and uses the C++ wrapper classes.
1223 * However, we will explain the implementation of a constraint handler using the C interface.
1224 * It is very easy to transfer the C explanation to C++; whenever a method should be implemented using the
1225 * SCIP_DECL_CONS... notion, reimplement the corresponding virtual member function of the abstract scip::ObjConshdlr
1226 * base class.
1227 *
1228 * Additional documentation for the callback methods of a constraint handler can be found in the file
1229 * type_cons.h.
1230 *
1231 * Here is what you have to do (assuming your constraint handler should be named "subtour"):
1232 * -# Copy the template files src/scip/cons_xyz.c and src/scip/cons_xyz.h into files "cons_subtour.c"
1233 * and "cons_subtour.h".
1234 * \n
1235 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
1236 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
1237 * -# Use `SCIPincludeConshdlrSubtour()` in order to include the constraint handler into your SCIP instance,
1238 * e.g., in the main file of your project (see, e.g., src/cppmain.cpp in the TSP example). \n
1239 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
1240 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "subtour".
1241 * -# Adjust the \ref CONS_PROPERTIES "properties of the constraint handler".
1242 * -# Define the \ref CONS_DATA "constraint data and the constraint handler data". This is optional.
1243 * -# Implement the \ref CONS_INTERFACE "interface methods".
1244 * -# Implement the \ref CONS_FUNDAMENTALCALLBACKS "fundamental callback methods".
1245 * -# Implement the \ref CONS_ADDITIONALCALLBACKS "additional callback methods". This is optional.
1246 *
1247 *
1248 * @section CONS_PROPERTIES Properties of a Constraint Handler
1249 *
1250 * At the top of the new file "cons_subtour.c" you can find the constraint handler properties.
1251 * These are given as compiler defines. Some of them are optional, as, e.g., separation-related properties,
1252 * which only have to be defined if the constraint handler supports the related callbacks.
1253 * In the C++ wrapper class, you have to provide the constraint handler properties by calling the constructor
1254 * of the abstract base class scip::ObjConshdlr from within your constructor (see the TSP example).
1255 * The properties you have to set have the following meaning:
1256 *
1257 * @subsection CONS_FUNDAMENTALPROPERTIES Fundamental Constraint Handler properties
1258 *
1259 * \par CONSHDLR_NAME: the name of the constraint handler.
1260 * This name is used in the interactive shell to address the constraint handler.
1261 * Additionally, if you are searching for a constraint handler with SCIPfindConshdlr(), this name is looked up.
1262 * Names have to be unique: no two constraint handlers may have the same name.
1263 *
1264 * \par CONSHDLR_DESC: the description of the constraint handler.
1265 * This string is printed as a description of the constraint handler in the interactive shell of SCIP.
1266 *
1267 * \par CONSHDLR_ENFOPRIORITY: the priority of the constraint handler for constraint enforcing.
1268 * Like the separation priority, the enforcement priorities define the order in which the different constraint handlers
1269 * are called in the constraint enforcement step of the subproblem processing.
1270 * The constraint enforcement is called after the price-and-cut loop is executed (in the case that the LP is solved
1271 * at the current subproblem).
1272 * \n
1273 * The integrality constraint handler has an enforcement priority of 0.
1274 * That means, if a constraint handler has negative enforcement priority, it only has to deal with integral solutions
1275 * in its enforcement methods, because for fractional solutions, the integrality constraint handler would have
1276 * created a branching, thereby aborting the enforcement step.
1277 * If you want to implement a constraint-depending branching rule (for example, SOS branching on special ordered
1278 * set constraints), you have to assign a positive enforcement priority to your constraint handler.
1279 * In this case, you have to be able to deal with fractional solutions.
1280 * \n
1281 * See \ref CONSENFOLP and \ref CONSENFOPS for further details of the separation callback.
1282 *
1283 * \par CONSHDLR_CHECKPRIORITY: the priority of the constraint handler for checking feasibility.
1284 * Like the separation priority, the checking priorities define the order in which the different constraint handlers
1285 * are called to check the feasibility of a given primal solution candidate.
1286 * The integrality constraint handler has a checking priority of 0.
1287 * That means, constraint handlers with negative checking priorities only have to deal with integral solutions.
1288 *
1289 * \par CONSHDLR_EAGERFREQ: the default frequency for using all instead of only the useful constraints in separation, propagation and enforcement.
1290 * If \em constraint \em aging is activated, some constraints that were not useful in the past for propagation or
1291 * separation are marked to be \em obsolete.
1292 * Usually, the obsolete constraints are not presented to the separation and propagation methods of the constraint
1293 * handlers, such that the constraint handlers only process the non-obsolete constraints.
1294 * However, every n'th call, with n being the EAGERFREQ of the constraint handler, all constraints are presented to the
1295 * separation and propagation methods of the constraint handler.
1296 * This gives obsolete constraints the chance of becoming non-obsolete again.
1297 * \n
1298 * If the eager evaluation frequency is set to -1, obsolete constraints are never presented to the separation and
1299 * propagation methods.
1300 * A frequency of 0 means, that obsolete constraints are only used in the first call of each method.
1301 *
1302 * \par CONSHDLR_NEEDSCONS: indicates whether the constraint handler should be skipped, if no constraints are available.
1303 * Usually, a constraint handler is only executed if there are constraints of its corresponding class in the model.
1304 * For those constraint handlers, the NEEDSCONS flag should be set to TRUE.
1305 * However, some constraint handlers must be called without having a constraint of the class in the model, because
1306 * the constraint is only implicitly available.
1307 * For example, the integrality constraint handler has the NEEDSCONS flag set to FALSE, because there is no explicit
1308 * integrality constraint in the model.
1309 * The integrality conditions are attached to the variables, and the integrality constraint handler has to check
1310 * all variables that are marked to be integer for integral values.
1311 *
1312 * @subsection CONS_ADDITIONALPROPERTIES Optional Constraint Handler properties
1313 *
1314 * The following properties are optional and only need to be defined if the constraint handlers support
1315 * separation, presolving, propagation, and/or upgrade functionality.
1316 *
1317 * \par LINCONSUPGD_PRIORITY: priority of the constraint handler for upgrading of linear constraints
1318 * This property is only needed if a certain linear constraint can be upgraded to a more specific one. In one of
1319 * the first presolving rounds SCIP tries to upgrade linear constraints to more specialized constraints, such as
1320 * knapsack constraints. The upgrading calls are processed in the order of decreasing priority.
1321 *
1322 * \par NONLINCONSUPGD_PRIORITY: priority of the constraint handler for upgrading of nonlinear constraints
1323 * This property has the same effect as the LINCONSUPGD_PRIORITY parameter, see above, and should be set whenever
1324 * an upgrade functionality from a general nonlinear constraint to the more specific one is defined.
1325 *
1326 * \par CONSHDLR_SEPAFREQ: the default frequency for separating cuts.
1327 * The separation frequency defines the depth levels at which the constraint handler's separation methods \ref CONSSEPALP
1328 * and \ref CONSSEPASOL are called.
1329 * For example, a separation frequency of 7 means, that the separation callback is executed for subproblems that are
1330 * in depth 0, 7, 14, ... of the branching tree.
1331 * A separation frequency of 0 means, that the separation method is only called at the root node.
1332 * A separation frequency of -1 disables the separation method of the constraint handler.
1333 * \n
1334 * The separation frequency can be adjusted by the user.
1335 * This property of the constraint handler only defines the default value of the frequency.
1336 * If you want to have a more flexible control of when to execute the separation algorithm, you have to assign
1337 * a separation frequency of 1 and implement a check at the beginning of your separation algorithm whether you really
1338 * want to execute the separator or not.
1339 * If you do not want to execute the method, set the result code to SCIP_DIDNOTRUN.
1340 *
1341 * \par CONSHDLR_SEPAPRIORITY: the priority of the constraint handler for separation. (optional: to be set only if the constraint handler supports separation)
1342 * In each separation round during the price-and-cut loop of the subproblem processing or during the separation loop
1343 * of the primal solution separation, the separators and separation methods of the constraint handlers are called in
1344 * a predefined order, which is given by the priorities of the separators and the separation priorities of the
1345 * constraint handlers.
1346 * First, the separators with non-negative priority are called in the order of decreasing priority.
1347 * Next, the separation methods of the different constraint handlers are called in the order of decreasing separation
1348 * priority.
1349 * Finally, the separators with negative priority are called in the order of decreasing priority.
1350 * \n
1351 * The separation priority of the constraint handler should be set according to the complexity of the cut separation
1352 * algorithm and the impact of the resulting cuts:
1353 * Constraint handlers that provide fast algorithms that usually have a high impact (i.e., cut off a large portion of
1354 * the LP relaxation) should have a high priority.
1355 * See \ref CONSSEPALP and \ref CONSSEPASOL for further details of the separation callbacks.
1356 *
1357 * \par CONSHDLR_DELAYSEPA: the default for whether the separation method should be delayed, if other separators found cuts.
1358 * If the constraint handler's separation method is marked to be delayed, it is only executed after no other separator
1359 * or constraint handler found a cut during the price-and-cut loop.
1360 * If the separation method of the constraint handler is very expensive, you may want to mark it to be delayed until all
1361 * cheap separation methods have been executed.
1362 *
1363 * \par CONSHDLR_PROPFREQ: the default frequency for propagating domains.
1364 * This default frequency has the same meaning as the CONSHDLR_SEPAFREQ with respect to the domain propagation
1365 * callback of the constraint handler.
1366 * A propagation frequency of 0 means that propagation is only applied in preprocessing and at the root node.
1367 * A propagation frequency of -1 disables the propagation method of the constraint handler.
1368 *
1369 * \par CONSHDLR_DELAYPROP: the default for whether the propagation method should be delayed, if other propagators found reductions.
1370 * This property is analogous to the DELAYSEPA flag, but deals with the propagation method of the constraint handler.
1371 *
1372 * \par CONSHDLR_PROP_TIMING: the propagation timing mask of the constraint handler.
1373 * SCIP calls the domain propagation routines at different places in the node processing loop.
1374 * This property indicates at which places the propagation routine of the constraint handler is called.
1375 * Possible values are defined in type_timing.h and can be concatenated, e.g., as in SCIP_PROPTIMING_ALWAYS.
1376 *
1377 * \par CONSHDLR_PRESOLTIMING: the timing of the constraint handler's presolving method (FAST, MEDIUM, or EXHAUSTIVE).
1378 * Every presolving round starts with the FAST presolving methods. MEDIUM presolvers are only called, if FAST presolvers did not find
1379 * enough reductions in this round so far, and EXHAUSTIVE presolving steps are only performed if all presolvers called before
1380 * in this round were unsuccessful.
1381 * Presolving methods should be assigned a timing based on how expensive they are, e.g., presolvers that provide fast algorithms that
1382 * usually have a high impact (i.e., remove lots of variables or tighten bounds of many variables) should have a timing FAST.
1383 * If a presolving method implements different algorithms of different complexity, it may also get multiple timings and check the timing
1384 * internally in the \ref CONSPRESOL callback to decide which algorithms to run.
1385 *
1386 * \par CONSHDLR_MAXPREROUNDS: the default maximal number of presolving rounds the constraint handler participates in.
1387 * The preprocessing is executed in rounds.
1388 * If enough changes have been applied to the model, an additional preprocessing round is performed.
1389 * The MAXPREROUNDS parameter of a constraint handler denotes the maximal number of preprocessing rounds the constraint
1390 * handler participates in.
1391 * A value of -1 means that there is no limit on the number of rounds.
1392 * A value of 0 means the preprocessing callback of the constraint handler is disabled.
1393 *
1394 *
1395 *
1396 * @section CONS_DATA Constraint Data and Constraint Handler Data
1397 *
1398 * Below the header "Data structures" you can find two structs called "struct SCIP_ConsData" and
1399 * "struct SCIP_ConshdlrData".
1400 * If you are using C++, you only need to define the "struct SCIP_ConsData".
1401 * The constraint handler data must be implemented as member variables of your constraint handler class.
1402 * \n
1403 * The constraint data are the information that is needed to define a single constraint of the constraint handler's
1404 * constraint class.
1405 * For example, the data of a knapsack constraint would consist of a list of variables, a list of weights, and
1406 * the capacity of the knapsack.
1407 * The data of a subtour constraint consists of the graph on which the problem is defined.
1408 * In the graph, each edge should be linked to the corresponding binary problem variable.
1409 * \n
1410 * The constraint handler data are additional variables, that belong to the constraint handler itself and which are
1411 * not specific to a single constraint.
1412 * For example, you can use these data to store parameters of the constraint handler or statistical information.
1413 * The constraint handler data are optional.
1414 * You can leave the struct empty.
1415 *
1416 *
1417 * @section CONS_INTERFACE Interface Methods
1418 *
1419 * At the bottom of "cons_subtour.c" you can find three interface methods, that also appear in "cons_subtour.h".
1420 * These are SCIPincludeConshdlrSubtour(), SCIPcreateConsSubtour(), and SCIPcreateConsSubtourBasic().
1421 * \n
1422 * The method SCIPincludeConshdlrSubtour() only has to be adjusted slightly.
1423 * It is responsible for notifying SCIP of the presence of the constraint handler by calling the method
1424 * SCIPincludeConshdlr().
1425 * It is called by the user, if (s)he wants to include the constraint handler, i.e., if (s)he wants to make
1426 * the constraint handler available to the model, and looks like this:
1427 * \dontinclude src/scip/cons_knapsack.c
1428 * -# If you are using constraint handler data, you have to <b>allocate the memory for the data</b> at this point.
1429 * You also have to initialize the fields in struct SCIP_ConshdlrData afterwards.
1430 *
1431 * \skip SCIP_RETCODE SCIPincludeConshdlrKnapsack(
1432 * \until SCIPallocBlockMemory
1433 *
1434 * -# Now, <b>SCIP gets notified</b> of the presence of the constraint handler together with its \ref CONS_FUNDAMENTALCALLBACKS "basic callbacks".
1435 *
1436 * \skip SCIPincludeConshdlrBasic
1437 * \until assert
1438 *
1439 * -# All \ref CONS_ADDITIONALCALLBACKS "additional callbacks" are added via their setter functions.
1440 *
1441 * \skip SCIPsetConshdlrCopy
1442 * \until SCIPsetConshdlrExit
1443 *
1444 * -# If the constraint handler is a specialization of a general linear or nonlinear constraint, we want to include an
1445 * <b>automatic upgrading mechanism</b> by calling the interface method
1446 *
1447 * \skip SCIPfindConshdlr
1448 * \until SCIPincludeLinconsUpgrade
1449 * or
1450 * \code
1451 * SCIP_CALL( SCIPincludeNonlinconsUpgrade(scip, nonlinconsUpgdSubtour, NULL, NONLINCONSUPGD_PRIORITY, TRUE, CONSHDLR_NAME) );
1452 * \endcode
1453 *
1454 * in the nonlinear case. See also cons_nonlinear.h for further information about the general upgrade procedure in the nonlinear case.
1455 * -# You may also add <b>user parameters</b> for your constraint handler.
1456 * Some parameters which are important to play with are added to every constraint automatically, as, e.g.,
1457 * propagation or separation frequency.
1458 * \skip SCIPaddIntParam
1459 * \until DEFAULT_SEPACARDFREQ
1460 * \skip SCIP_OKAY
1461 * \until }
1462 *
1463 *
1464 * The methods SCIPcreateConsSubtour() and SCIPcreateConsSubtourBasic() are called to create a single constraint of the constraint
1465 * handler's constraint class.
1466 * It should allocate and fill the constraint data, and call SCIPcreateCons().
1467 * Take a look at the following example from the \ref cons_knapsack.h "knapsack constraint handler":
1468 *
1469 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsCreationKnapsack}
1470 *
1471 * In this example, consdataCreate() is a local method that allocates memory for the given consdata
1472 * and fills the data with the given <code>vars</code> array. For allocating memory for the constraint data, you
1473 * can use SCIP memory allocation:
1474 * \code
1475 * SCIP_CALL( SCIPallocBlockMemory(scip, consdata) );
1476 * \endcode
1477 *
1478 *
1479 * @section CONS_CALLBACKS Callback methods of Constraint handlers
1480 *
1481 * Besides the various functions which you will implement inside your constraint handler there exists a number
1482 * of <b> callback methods </b> associated with your constraint handler. Callback methods can be regarded as
1483 * tasks which your constraint handler is able to provide to the solver. They are grouped into two
1484 * categories:
1485 *
1486 * \ref CONS_FUNDAMENTALCALLBACKS "Fundamental Callback methods" are mandatory to implement
1487 * such that your code will work. For example, every constraint handler has to provide the
1488 * functionality to state whether all of its constraints are
1489 * fulfilled by a given variable assignment. Hence, the \ref CONSCHECK "CONSCHECK" callback is
1490 * one of the fundamental (or \a basic) callbacks of a constraint handler.
1491 *
1492 * Callbacks which are not necessarily implemented are grouped together as
1493 * \ref CONS_ADDITIONALCALLBACKS "additional callbacks". Such callbacks can be used to allocate and free memory
1494 * at different stages of the solving process. Although not mandatory, it might be useful to implement
1495 * some of these callbacks, e.g., to extend your constraint handler by a
1496 * \ref CONSSEPALP "separation" or \ref CONSPRESOL "presolving" functionality.
1497 *
1498 * All callbacks should be passed to SCIP during the SCIPinclude<PLUGINTYPE><PLUGINNAME> method
1499 * (e.g., SCIPincludeConshdlrKnapsack() for the \ref cons_knapsack.h "knapsack constraint handler").
1500 * Since SCIP version 3.0, two ways of setting callbacks can be used, either via SCIPincludeConshdlr()
1501 * (all at once, as it always was), or via SCIPincludeConshdlrBasic() and setter functions for additional callbacks.
1502 * Since the basic inclusion methods are very unlikely to change and will thus
1503 * make your code more stable towards future versions of SCIP with more callbacks,
1504 * we recommend the latter choice, as explained in the \ref CONS_INTERFACE "interface" section.
1505 *
1506 * @section CONS_FUNDAMENTALCALLBACKS Fundamental Callback Methods
1507 *
1508 * By implementing the fundamental callbacks, you define the semantics of the constraint class the constraint handler
1509 * deals with.
1510 * If these methods are implemented, the resulting code is already correct and finds the optimal solution to the
1511 * given problem instance.
1512 * However, it might be very slow because the additional features, like cut separation and domain propagation, are
1513 * missing.
1514 * In the C++ wrapper class scip::ObjConshdlr, the fundamental callback methods are virtual abstract member functions.
1515 * You have to implement them in order to be able to construct an object of your constraint handler class.
1516 *
1517 * There are three fundamental callback methods that are all dealing with the feasibility of a given solution.
1518 * They are called at different places in the algorithm and have slightly different meaning.
1519 * However, it is usually reasonable to implement a single local method that is called by all of the three callback
1520 * methods with slightly modified parameters.
1521 * The fourth method provides dual information that is used for example in preprocessing.
1522 *
1523 * Additional documentation for the callback methods can be found in type_cons.h.
1524 *
1525 * @subsection CONSCHECK
1526 *
1527 * The CONSCHECK callback gets a primal solution candidate in a SCIP_SOL* data structure
1528 * and has to check this solution for global feasibility.
1529 * It has to return a result SCIP_FEASIBLE, if the solution satisfies all the constraints of the constraint handler,
1530 * and a result SCIP_INFEASIBLE if there is at least one constraint that is violated.
1531 *
1532 * If the solution is not NULL, SCIP should also be informed about the constraint violation with a call to
1533 * SCIPupdateSolConsViolation() and additionally SCIPupdateSolLPRowViolation() for every row of the constraint's current
1534 * representation in the LP relaxation, if any such rows exist.
1535 * As a convenience method, SCIPupdateSolLPConsViolation() can be used if the constraint
1536 * is represented completely by a set of LP rows, meaning that the current constraint violation is equal to the maximum
1537 * of the contraint violations of the corresponding LP rows.
1538 *
1539 * The callback is used by primal heuristics to check a constructed solution for feasibility.
1540 * That means, the constraint handler has to deal with arbitrary solutions that do not necessarily satisfy the bounds
1541 * and constraints of the local subproblem.
1542 *
1543 * The value of a variable \em var in the given solution \em sol can be accessed by calling
1544 * \code
1545 * SCIPgetSolVal(scip, sol, var)
1546 * \endcode
1547 *
1548 * For example, the \ref cons_knapsack.h "knapsack constraint handler" loops over its constraints and
1549 * calculates the scalar product \f$w^T x\f$ of weights \f$w\f$ with the solution vector \f$x\f$.
1550 * This scalar product is compared with the capacity of the knapsack constraint.
1551 * If it exceeds the capacity, the CONSCHECK method is immediately aborted with the result SCIP_INFEASIBLE.
1552 * If all knapsack constraints are satisfied, a result SCIP_FEASIBLE is returned.
1553 *
1554 * @subsection CONSENFOLP
1555 *
1556 * The CONSENFOLP method is called after the price-and-cut loop was finished and an LP solution is available.
1557 * Like the CHECK call, the ENFOLP method should return a result SCIP_FEASIBLE, if the solution satisfies all the
1558 * constraints.
1559 * However, the behavior should be different, if the solution violates some of the associated constraints.
1560 * The constraint handler may return a result SCIP_INFEASIBLE in this situation, but this is not the best what
1561 * one can do.
1562 * The ENFOLP method has the possibility of \em resolving the infeasibility by
1563 * - stating that the current subproblem is infeasible (result SCIP_CUTOFF),
1564 * - adding an additional constraint that resolves the infeasibility (result SCIP_CONSADDED),
1565 * - reducing the domain of a variable (result SCIP_REDUCEDDOM),
1566 * - adding a cutting plane (result SCIP_SEPARATED),
1567 * - tightening the LP primal feasibility tolerance and requesting to solve the LP again (result SCIP_SOLVELP),
1568 * - performing a branching (result SCIP_BRANCHED).
1569 *
1570 * Note that in case SCIP_CONSADDED, the added constraints must be created with flag initial=TRUE.
1571 *
1572 * However, the solution is not given as a SCIP_SOL* data structure.
1573 *
1574 * The value of a variable <code>var</code> in the LP solution can be accessed by calling
1575 * \code
1576 * SCIPgetVarSol(scip, var)
1577 * \endcode
1578 * or by
1579 * \code
1580 * SCIPgetSolVal(scip, NULL, var)
1581 * \endcode
1582 * By using the latter method, you can have a single local method to check a solution for feasibility by passing
1583 * the given <code>sol</code> to the CONSCHECK call and by passing a NULL pointer as <code>sol</code> to
1584 * the CONSENFOLP and CONSENFOPS calls.
1585 *
1586 *
1587 * @subsection CONSENFOPS
1588 *
1589 * The CONSENFOPS callback is similar to the CONSENFOLP callback, but deals with \em pseudo \em solutions instead
1590 * of LP solutions.
1591 *
1592 * If the LP was not solved at the current subproblem (either because the user did not want to solve it, or because
1593 * numerical difficulties in the LP solving process were detected) no LP solution is available.
1594 * In this situation, the pseudo solution is used instead.
1595 * In this solution, the variables are set to the local bound which is best with respect to the objective function.
1596 * You can think of the pseudo solution as solution to the LP relaxation with all constraints except the bounds
1597 * being removed.
1598 *
1599 * Like the ENFOLP callback, the ENFOPS callback has to check whether the pseudo solution satisfies all the constraints
1600 * of the constraint handler.
1601 * The pseudo solution can be accessed by the same methods as the LP solution (SCIP knows, if the LP was solved at the
1602 * current subproblem, and returns either the LP solution or the pseudo solution).
1603 *
1604 * Unlike the ENFOLP callback, the ENFOPS callback must not add cuts and cannot return the result SCIP_SEPARATED.
1605 * It is, however, possible to force the solving of the LP by returning the result SCIP_SOLVELP.
1606 * For example, the infeasibility of a linear constraint that contains continuous variables cannot be resolved,
1607 * if all integer variables in the constraint are already fixed.
1608 * In this case, the LP has to be solved in order to get a solution that satisfies the linear constraint.
1609 *
1610 * @subsection CONSENFORELAX
1611 *
1612 * The CONSENFORELAX callback is similar to the CONSENFOLP and CONSENFOPS callbacks, but deals with relaxation solutions.
1613 *
1614 * If the best bound computed by a relaxator that includes the whole LP is strictly better than the bound of the LP itself,
1615 * the corresponding relaxation solution will get enforced. Therefore the CONSENFORELAX callback will only be called for
1616 * solutions that satisfy all active LP-constraints.
1617 *
1618 * Like the ENFOLP and ENFOPS callbacks, the ENFORELAX callback has to check whether the solution given in sol satisfies
1619 * all the constraints of the constraint handler. Since the callback is only called for relaxators including the whole LP,
1620 * cuts may be added with a result of SCIP_SEPARATED, like in the ENFOLP callback. It is also possible to return
1621 * SCIP_SOLVELP if the relaxation solution is invalid for some reason and the LP should be solved instead.
1622 *
1623 * Note that the CONSENFORELAX callback is only relevant if relaxators are used. Since the basic distribution of the
1624 * SCIP Optimization Suite does not contain any relaxators, this callback can be ignored unless any relaxators are added
1625 * via user-plugins.
1626 *
1627 * @subsection CONSLOCK
1628 *
1629 * The CONSLOCK callback provides dual information for a single constraint.
1630 * It has to tell SCIP, which variables are existing in the given constraint, and in which way modifications of these
1631 * variables may affect the feasibility of the constraint.
1632 *
1633 * For each variable that is affected by the constraint, the callback should call SCIPaddVarLocks():
1634 * - If the constraint may become violated by decreasing the value of a variable, it should call
1635 * SCIPaddVarLocks(scip, var, nlockspos, nlocksneg), saying that rounding down is potentially rendering the
1636 * (positive) constraint infeasible and rounding up is potentially rendering the negation of the constraint
1637 * infeasible.
1638 * - If the constraint may become violated by increasing the value of a variable, it should call
1639 * SCIPaddVarLocks(scip, var, nlocksneg, nlockspos), saying that rounding up is potentially rendering the
1640 * constraint's negation infeasible and rounding down is potentially rendering the constraint itself
1641 * infeasible.
1642 * - If the constraint may become violated by changing the variable in any direction, it should call
1643 * SCIPaddVarLocks(scip, var, nlockspos + nlocksneg, nlockspos + nlocksneg).
1644 *
1645 * <b>Note:</b> You do not have to worry about nlockspos and nlocksneg. These integer values are given as
1646 * parameter of the CONSLOCK callback (see type_cons.h). Just use these variables in the above described
1647 * fashion <b>without</b> adding or subtracting anything to them. In case of the knapsack constraints this
1648 * method looks like this.
1649 *
1650 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsLockKnapsack}
1651 *
1652 * To give same more intuition, consider the linear constraint \f$3x -5y +2z \leq 7\f$ as an example.
1653 * The CONSLOCK callback method of the linear constraint handler should call
1654 * SCIPaddVarLocks(scip, x, nlocksneg, nlockspos), SCIPaddVarLocks(scip, y, nlockspos, nlocksneg),
1655 * and SCIPaddVarLocks(scip, z, nlocksneg, nlockspos) to tell SCIP, that rounding up of \f$x\f$
1656 * and \f$z\f$ and rounding down of \f$y\f$ can destroy the feasibility of the constraint, while rounding
1657 * down of \f$x\f$ and \f$z\f$ and rounding up of \f$y\f$ can destroy the feasibility of the
1658 * constraint's negation \f$3x -5y +2z > 7\f$.
1659 * \n
1660 * A linear constraint \f$2 \leq 3x -5y +2z \leq 7\f$ should call
1661 * SCIPaddVarLocks(scip, ..., nlockspos + nlocksneg, nlockspos + nlocksneg) on all variables,
1662 * since rounding in both directions of each variable can destroy both the feasibility of the
1663 * constraint and it's negation \f$3x -5y +2z < 2\f$ or \f$3x -5y +2z > 7\f$.
1664 *
1665 *
1666 * @section CONS_ADDITIONALCALLBACKS Additional Callback Methods
1667 *
1668 * The additional callback methods do not need to be implemented in every case, but provide useful functionality
1669 * for many applications. They can be added to your constraint handler via setter functions, see
1670 * \ref CONS_INTERFACE "here".
1671 *
1672 * @subsection CONSFREE
1673 *
1674 * If you are using constraint handler data, you have to implement this method in order to free the
1675 * constraint handler data. This can be done by the following procedure (which is taken from the
1676 * \ref cons_knapsack.h "knapsack constraint handler"):
1677 *
1678 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsFreeKnapsack}
1679 *
1680 * If you have allocated memory for fields in your constraint handler data, remember to free this memory
1681 * before freeing the constraint handler data itself.
1682 * If you are using the C++ wrapper class, this method is not available.
1683 * Instead, just use the destructor of your class to free the member variables of your class.
1684 *
1685 * @subsection CONSHDLRCOPY
1686 *
1687 * The CONSHDLRCOPY callback is executed when the SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
1688 * callback as <code>NULL</code> the user disables the inclusion of the specified constraint handler into all copied SCIP
1689 * instances. This may deteriorate the performance of primal heuristics solving sub-SCIPs, since these constitute only
1690 * relaxations of the original problem if constraint handlers are missing.
1691 *
1692 * A usual implementation just
1693 * calls the interface method which includes the constraint handler to the model. For example, this callback is
1694 * implemented for the \ref cons_knapsack.c "knapsack constraint handler" as follows:
1695 *
1696 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsCopyKnapsack}
1697 *
1698 * <b>Note:</b> If you implement this callback, take care when setting the valid pointer.
1699 *
1700 * A problem copy is called valid if it is valid in both the primal and the dual sense, i.e., if
1701 *
1702 * - it is a relaxation of the source problem
1703 * - it does not enlarge the feasible region.
1704 *
1705 * A constraint handler may choose to not copy a constraint and still declare the resulting copy as valid. It must ensure
1706 * the feasibility of any solution to the problem copy in the original (source) space.
1707 *
1708 * <b>Note:</b> If you implement this callback and the constraint handler needs constraints (see CONSHDLR_NEEDSCONS),
1709 * then you also need to implement the callback \ref CONSCOPY.
1710 *
1711 * @subsection CONSINIT
1712 *
1713 * The CONSINIT callback is executed after the problem is transformed.
1714 * The constraint handler may, e.g., use this call to replace the original variables in its constraints by transformed
1715 * variables, or to initialize its statistical constraint handler data.
1716 *
1717 * @subsection CONSEXIT
1718 *
1719 * The CONSEXIT callback is executed before the transformed problem is freed.
1720 * In this method, the constraint handler should free all resources that were allocated for the solving process.
1721 *
1722 * @subsection CONSINITPRE
1723 *
1724 * The CONSINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
1725 * The constraint handler may use this call to initialize its presolving data, or to modify its constraints
1726 * before the presolving process begins.
1727 * Necessary constraint modifications that have to be performed even if presolving is turned off should be done here
1728 * or in the presolving deinitialization call.
1729 *
1730 * @subsection CONSEXITPRE
1731 *
1732 * The CONSEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
1733 * The constraint handler may use this call e.g. to clean up its presolving data, or to finally modify its constraints
1734 * before the branch-and-bound process begins.
1735 * Necessary constraint modifications that have to be performed even if presolving is turned off should be done here
1736 * or in the presolving initialization call.
1737 * Besides necessary modifications and clean up, no time consuming operations should be done.
1738 *
1739 * @subsection CONSINITSOL
1740 *
1741 * The CONSINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
1742 * begin.
1743 * The constraint handler may use this call to initialize its branch-and-bound specific data.
1744 *
1745 * @subsection CONSEXITSOL
1746 *
1747 * The CONSEXITSOL callback is executed before the branch-and-bound process is freed.
1748 * The constraint handler should use this call to clean up its branch-and-bound data, in particular to release
1749 * all LP rows that it has created or captured.
1750 *
1751 * @subsection CONSDELETE
1752 *
1753 * The CONSDELETE callback is executed if a constraint should be freed.
1754 * You can think of it as the destructor of a single constraint.
1755 * In the callback, you have to free the given constraint data.
1756 * The CONSDELETE callback is therefore the counterpart of the SCIPcreateCons...() interface method and the CONSTRANS
1757 * method.
1758 *
1759 * @subsection CONSTRANS
1760 *
1761 * The CONSTRANS method is called for each constraint of the constraint handler, when the user starts the solving
1762 * process.
1763 * It has to copy the original constraint data of the constraint to the memory for the transformed problem.
1764 * You can think of it as a copy constructor for a single constraint.
1765 *
1766 * The original model is copied in order to protect it from transformations that are applied during the solving process,
1767 * in particular during preprocessing.
1768 * Preprocessing and solving always operates on the transformed problem.
1769 * If the solving process data are freed, the original data still exist and the user can, e.g., modify the problem and
1770 * restart the solving process.
1771 *
1772 * If you do not implement the CONSTRANS method, a transformed constraint is created with the same flags and the
1773 * same constraint data pointer.
1774 * That means, the transformed constraint points to the original constraint data.
1775 * This is okay, as long as the constraint data is not changed during the solving process.
1776 * If you want to implement preprocessing methods or other methods that modify the constraint data, you have to
1777 * implement the CONSTRANS method and create a copy of the constraint data.
1778 *
1779 * Here is an example, which is taken from the \ref cons_knapsack.h "knapsack constraint handler":
1780 *
1781 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsTransKnapsack}
1782 *
1783 * @subsection CONSINITLP
1784 *
1785 * The CONSINITLP callback is executed before the first LP relaxation is solved.
1786 * It should add the LP relaxations of all "initial" constraints to the LP. The method should scan the constraints
1787 * array for constraints that are marked initial via calls to SCIPconsIsInitial() and put the LP relaxation
1788 * of all initial constraints to the LP with calls to SCIPaddCut().
1789 *
1790 * @subsection CONSSEPALP
1791 *
1792 * The CONSSEPALP callback is executed during the price-and-cut loop of the subproblem processing.
1793 * It should try to generate cutting planes for the constraints of the constraint handler in order to separate
1794 * the current LP solution.
1795 * The method is called in the LP solution loop, which means that a valid LP solution exists.
1796 *
1797 * Usually, a separation callback searches and produces cuts, that are added with a call to SCIPaddCut().
1798 * If the cut should be remembered in the global cut pool, it may also call SCIPaddPoolCut().
1799 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
1800 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
1801 * However, the callback may also produce domain reductions or add other constraints.
1802 *
1803 * The CONSSEPALP callback has the following options:
1804 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1805 * - adding an additional constraint (result SCIP_CONSADDED)
1806 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1807 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
1808 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
1809 * (result SCIP_DIDNOTFIND)
1810 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
1811 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
1812 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
1813 *
1814 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1815 * CONSHDLR_SEPAFREQ, CONSHDLR_SEPAPRIORITY, and CONSHDLR_DELAYSEPA, which influence the behaviour of SCIP
1816 * calling CONSSEPALP.
1817 *
1818 * @subsection CONSSEPASOL
1819 *
1820 * The CONSSEPASOL callback is executed during separation loop on arbitrary primal solutions.
1821 * It should try to generate cutting planes for the constraints of the constraint handler in order to separate
1822 * the given primal solution.
1823 * The method is not called in the LP solution loop, which means that there is no valid LP solution.
1824 *
1825 * Usually, a separation callback searches and produces cuts, that are added with a call to SCIPaddCut().
1826 * If the cut should be remembered in the global cut pool, it may also call SCIPaddPoolCut().
1827 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
1828 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
1829 * However, the callback may also produce domain reductions or add other constraints.
1830 *
1831 * The CONSSEPASOL callback has the following options:
1832 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1833 * - adding an additional constraint (result SCIP_CONSADDED)
1834 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1835 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
1836 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
1837 * (result SCIP_DIDNOTFIND)
1838 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
1839 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
1840 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
1841 *
1842 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1843 * CONSHDLR_SEPAFREQ, CONSHDLR_SEPAPRIORITY, and CONSHDLR_DELAYSEPA, which influence the behaviour of SCIP
1844 * calling CONSSEPASOL.
1845 *
1846 * @subsection CONSPROP
1847 *
1848 * The CONSPROP callback is called during the subproblem processing.
1849 * It should propagate the constraints, which means that it should infer reductions in the variables' local bounds
1850 * from the current local bounds.
1851 * This technique, which is the main workhorse of constraint programming, is called "node preprocessing" in the
1852 * Integer Programming community.
1853 *
1854 * The CONSPROP callback has the following options:
1855 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1856 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1857 * - stating that the propagator searched, but did not find domain reductions, cutting planes, or cut constraints
1858 * (result SCIP_DIDNOTFIND)
1859 * - stating that the propagator was skipped (result SCIP_DIDNOTRUN)
1860 * - stating that the propagator was skipped, but should be called again (result SCIP_DELAYED)
1861 *
1862 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1863 * CONSHDLR_PROPFREQ, CONSHDLR_DELAYPROP, and CONSHDLR_PROP_TIMING, which influence the behaviour of SCIP
1864 * calling CONSPROP.
1865 *
1866 * @subsection CONSRESPROP
1867 *
1868 * If the constraint handler should support \ref CONF "conflict analysis", it has to supply a CONSRESPROP method.
1869 * It also should call SCIPinferVarLbCons() or SCIPinferVarUbCons() in domain propagation instead of SCIPchgVarLb() or
1870 * SCIPchgVarUb() in order to deduce bound changes on variables.
1871 * In the SCIPinferVarLbCons() and SCIPinferVarUbCons() calls, the handler provides the constraint that deduced the
1872 * variable's bound change, and an integer value <code>inferinfo</code> that can be arbitrarily chosen.
1873 *
1874 * The propagation conflict resolving method CONSRESPROP must then be implemented to provide the "reasons" for the bound
1875 * changes, i.e., the bounds of variables at the time of the propagation, which forced the constraint to set the
1876 * conflict variable's bound to its current value. It can use the <code>inferinfo</code> tag to identify its own propagation rule
1877 * and thus identify the "reason" bounds. The bounds that form the reason of the assignment must then be provided by
1878 * calls to SCIPaddConflictLb() and SCIPaddConflictUb() in the propagation conflict resolving method.
1879 *
1880 * <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
1881 * need more information to efficiently infer the original propagation steps that lead to the conflict. This would,
1882 * however, require too much space. In the extreme, the original propagation steps have to be repeated.
1883 *
1884 * 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
1885 * 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
1886 * variables are 0.0). It uses <code>SCIPinferVarLbCons(scip, z, 1.0, c, 0)</code> to apply this assignment (an
1887 * inference information tag is not needed by the constraint handler and is set to 0). In the conflict analysis, the
1888 * constraint handler may be asked to resolve the lower bound change on \f$z\f$ with constraint \f$c\f$, that was
1889 * applied at a time given by a bound change index "bdchgidx". With a call to <code>SCIPvarGetLbAtIndex(z,
1890 * bdchgidx)</code>, the handler can find out, that the lower bound of variable \f$z\f$ was set to 1.0 at the given
1891 * point of time, and should call <code>SCIPaddConflictUb(scip, x, bdchgidx)</code> and <code>SCIPaddConflictUb(scip, y,
1892 * 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
1893 * the deduction of the lower bound of \f$z\f$.
1894 *
1895 * If conflict analysis should not be supported, the method has to set the result code to SCIP_DIDNOTFIND. Although
1896 * this is a viable approach to circumvent the implementation of the usually rather complex conflict resolving method, it
1897 * will make the conflict analysis less effective. We suggest to first omit the conflict resolving method and check how
1898 * effective the \ref CONSPROP "propagation method" is. If it produces a lot of propagations for your application, you definitely should
1899 * consider implementing the conflict resolving method.
1900 *
1901 * @subsection CONSPRESOL
1902 *
1903 * The CONSPRESOL callback is called during preprocessing.
1904 * It should try to tighten the domains of the variables, tighten the coefficients of the constraints of the constraint
1905 * handler, delete redundant constraints, aggregate and fix variables if possible, and upgrade constraints to more
1906 * specific types.
1907 *
1908 * If the CONSPRESOL callback applies changes to the constraint data, you also have to implement the \ref CONSTRANS callback
1909 * in order to copy the constraint data to the transformed problem space and protect the original problem from the
1910 * preprocessing changes.
1911 *
1912 * To inform SCIP that the presolving method found a reduction the result pointer has to be set in a proper way.
1913 * The following options are possible:
1914 *
1915 * - SCIP_UNBOUNDED : at least one variable is not bounded by any constraint in objective direction
1916 * - SCIP_CUTOFF : at least one constraint is infeasible in the variable's bounds
1917 * - SCIP_SUCCESS : the presolver found a reduction
1918 * - SCIP_DIDNOTFIND : the presolver searched, but did not find a presolving change
1919 * - SCIP_DIDNOTRUN : the presolver was skipped
1920 * - SCIP_DELAYED : the presolver was skipped, but should be called again
1921 *
1922 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1923 * CONSHDLR_PRESOLTIMING and CONSHDLR_MAXPREROUNDS, which influence the behaviour of SCIP
1924 * calling CONSPRESOL.
1925 *
1926 * @subsection CONSACTIVE
1927 *
1928 * The CONSACTIVE callback method is called each time a constraint of the constraint handler is activated.
1929 * For example, if a constraint is added locally to a subproblem, the CONSACTIVE callback is called whenever the
1930 * search enters the subtree where the constraint exists.
1931 *
1932 * @subsection CONSDEACTIVE
1933 *
1934 * The CONSDEACTIVE callback method is called each time a constraint of the constraint handler is deactivated.
1935 * For example, if a constraint is added locally to a subproblem, the CONSDEACTIVE callback is called whenever the
1936 * search leaves the subtree where the constraint exists.
1937 *
1938 * @subsection CONSENABLE
1939 *
1940 * The CONSENABLE callback method is called each time a constraint of the constraint handler is enabled.
1941 * Constraints might be active without being enabled. In this case, only the feasibility checks are executed,
1942 * but domain propagation and separation is skipped.
1943 *
1944 * @subsection CONSDISABLE
1945 *
1946 * The CONSDISABLE callback method is called each time a constraint of the constraint handler is disabled.
1947 *
1948 * @subsection CONSPRINT
1949 *
1950 * The CONSPRINT callback method is called, when the user asks SCIP to display the problem to the screen
1951 * or save the problem into a file. This is, however, only the case if the user requested the CIP format.
1952 * For more details about reading and writing with SCIP we refer to the \ref READER "file readers". In this
1953 * callback method the constraint handler should display the data of the constraint in an appropriate form.
1954 * The output format that is defined by the CONSPRINT callbacks is called CIP format.
1955 * In later versions of SCIP, the constraint handlers should also be able to parse (i.e., read) constraints
1956 * which are given in CIP format.
1957 *
1958 * @subsection CONSCOPY
1959 *
1960 * The CONSCOPY callback method is used whenever constraints should be copied from one SCIP instance into another SCIP
1961 * instance. This method comes with the necessary parameters to do so, most importantly with a mapping of the variables of the
1962 * source SCIP instance to the corresponding variables of the target SCIP instance, and a mapping for the constraints
1963 * in the same way. For a complete list of all arguments of this callback method see type_cons.h.
1964 *
1965 * To get the corresponding target variable of a given source variable, you can use the variable map directly:
1966 *
1967 * \code
1968 * targetvar = (SCIP_VAR*) SCIPhashmapGetImage(varmap, sourcevar);
1969 * \endcode
1970 *
1971 * We recommend, however, to use the method SCIPgetVarCopy() which gets besides others the variable map and the constraint map as input
1972 * and returns the requested target variable. The advantage of using SCIPgetVarCopy() is that in the case
1973 * the required variable does not yet exist, it is created and added to the copy automatically:
1974 *
1975 * \code
1976 * SCIP_CALL( SCIPgetVarCopy(sourcescip, scip, sourcevar, &targetvar, varmap, consmap, global) );
1977 * \endcode
1978 *
1979 * Finally, the result pointer <code>valid</code> has to be set to TRUE if (and only if!) the copy process was successful.
1980 *
1981 * <b>Note:</b> Be careful when setting the valid pointer.
1982 * A problem copy is called valid if it is valid in both the primal and the dual sense, i.e., if
1983 *
1984 * - it is a relaxation of the source problem
1985 * - it does not enlarge the feasible region.
1986 *
1987 * A constraint handler may choose to not copy a constraint and still declare the resulting copy as valid. Therefore, it must ensure
1988 * the feasibility of any solution to the problem copy in the original (source) space.
1989 *
1990 * For an example implementation we refer to cons_linear.h. Additional documentation and the complete list of all
1991 * parameters can be found in the file in type_cons.h.
1992 *
1993 * @subsection CONSPARSE
1994 *
1995 * This method is the counter part to CONSPRINT. The ideal idea is that a constraint handler is able to parse the output
1996 * which it generated via the CONSPRINT method and creates the corresponding constraint. If the parsing was successfully
1997 * the result pointer success should be set to TRUE. An example implementation can be found in the \ref cons_linear.h
1998 * "linear constraint handler".
1999 *
2000 * @subsection CONSDELVARS
2001 *
2002 * This method should iterate over the given constraints and delete all variables that were marked for deletion by SCIPdelVar().
2003 * Variable deletion is especially interesting for branch-cut-and-price applications. If your constraint handler allows
2004 * the addition of variables during the solving process (see "modifiable" attribute of constraints), then you might also want to
2005 * implement this callback. This would allow you to not only create variables during solving, but also remove them dynamically
2006 * from the problem to reduce memory consumption in case they are no longer necessary.
2007 * During presolving, SCIP may also find that some variables are not needed anymore and then try
2008 * to delete them. Thus, if you do not implement this callback, the constraint handler should capture its variables via
2009 * SCIPcaptureVar() to prevent SCIP from erroneously deleting them.
2010 *
2011 * Additional documentation and the complete list of all parameters can be found in the file type_cons.h.
2012 *
2013 * @subsection CONSGETVARS
2014 *
2015 * The CONSGETVARS callback of a constraint handler can be implemented to give access to the constraint variables
2016 * as array, independently from the internal data structure of the constraint. The buffer array
2017 * is already passed, together with its length. Consider implementing @ref CONSGETNVARS, too, to have
2018 * information about the number of variables in this constraint.
2019 *
2020 * @subsection CONSGETNVARS
2021 *
2022 * This callback can be implemented to return the number of variables involved into a particular constraint.
2023 * In order to have access to the variable pointers, consider implementing @ref CONSGETVARS.
2024 *
2025 * @refsnippet{src/scip/cons_linear.c,Callback for the number of variables}
2026 *
2027 * @subsection CONSGETDIVEBDCHGS
2028 *
2029 * This callback is used inside the various diving heuristics of SCIP and does not affect the normal branching
2030 * of the actual search.
2031 * The constraint handler can provide this callback to render a current working solution (even more) infeasible by
2032 * suggesting one or several variable bound changes.
2033 *
2034 * @section CONS_FURTHERINFO Further documentation
2035 *
2036 * Further documentation can be found in @ref type_cons.h for callback descriptions and a complete
2037 * list of all callback parameters, or in @ref scip.h
2038 * for globally available functions.
2039 */
2040
2041/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2042
2043/**@page PRICER How to add variable pricers
2044 *
2045 * A pricer performs the dynamic generation of new variables in a column generation algorithm.
2046 * It is an algorithmic representation of a (usually exponential) number of variables.
2047 * The \ref PRICERREDCOST and \ref PRICERFARKAS methods are called after each LP solve to generate additional
2048 * variables which may improve the objective value or decrease the LP infeasibility, respectively.
2049 * \n
2050 * A complete list of all pricers contained in this release can be found \ref PRICERS "here".
2051 *
2052 * If the pricer finds one or more variables with negative reduced costs or negative Farkas value, it should
2053 * call SCIPcreateVar() and SCIPaddPricedVar() to create and add the variable to the problem. Additionally,
2054 * the pricer has to add the variable to all constraints in which it appears. Therefore, a pricer needs to
2055 * know the constraints of the model and their meaning. Note that all constraints for which additional variables
2056 * are generated by a pricer have to be flagged as "modifiable" in the SCIPcreateCons() call.
2057 *
2058 * We now explain how users can add their own pricers.
2059 * For example, look into the variable pricer for the binpacking problem (examples/Binpacking/src/pricer_binpacking.c) of the
2060 * Binpacking example project.
2061 * The example is written in C. C++ users can easily adapt the code by using the scip::scip::ObjPricer wrapper base class and
2062 * implement the scip_...() virtual methods instead of the SCIP_DECL_PRICER... callback methods.
2063 *
2064 * Additional documentation for the callback methods of a pricer can be found in the file
2065 * type_pricer.h.
2066 *
2067 * Notice that if your pricer cannot cope with variable bounds other than 0 and infinity, you have to mark
2068 * all constraints containing priced variables as modifiable, and you may have to disable reduced cost
2069 * strengthening by setting propagating/rootredcost/freq to -1.
2070 *
2071 * Here is what you have to do to implement a pricer:
2072 * -# Copy the template files src/scip/pricer_xyz.c and src/scip/pricer_xyz.h into files "pricer_mypricer.c"
2073 * and "pricer_mypricer.h".
2074 * \n
2075 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2076 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2077 * -# Use `SCIPincludePricerMypricer()` in order to include the pricer into your SCIP instance,
2078 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2079 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2080 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypricer".
2081 * -# Adjust the properties of the pricer (see \ref PRICER_PROPERTIES).
2082 * -# Define the pricer data (see \ref PRICER_DATA). This is optional.
2083 * -# Implement the interface methods (see \ref PRICER_INTERFACE).
2084 * -# Implement the fundamental callback methods (see \ref PRICER_FUNDAMENTALCALLBACKS).
2085 * -# Implement the additional callback methods (see \ref PRICER_ADDITIONALCALLBACKS). This is optional.
2086 *
2087 *
2088 * @section PRICER_PROPERTIES Properties of a Pricer
2089 *
2090 * At the top of the new file "pricer_mypricer.c" you can find the pricer properties.
2091 * These are given as compiler defines.
2092 * In the C++ wrapper class, you have to provide the pricer properties by calling the constructor
2093 * of the abstract base class scip::ObjPricer from within your constructor.
2094 * The properties you have to set have the following meaning:
2095 *
2096 * \par PRICER_NAME: the name of the pricer.
2097 * This name is used in the interactive shell to address the pricer.
2098 * Additionally, if you are searching for a pricer with SCIPfindPricer(), this name is looked up.
2099 * Names have to be unique: no two pricers may have the same name.
2100 *
2101 * \par PRICER_DESC: the description of the pricer.
2102 * This string is printed as a description of the pricer in the interactive shell.
2103 *
2104 * \par PRICER_PRIORITY: the priority of the pricer.
2105 * In each pricing round during the price-and-cut loop of the subproblem processing, the included pricers are
2106 * called in a predefined order, which is given by the priorities of the pricers.
2107 * The higher the priority, the earlier the pricer is called.
2108 * Usually, you will have only one pricer in your application and the priority is therefore irrelevant.
2109 *
2110 * \par PRICER_DELAY: the default for whether the pricer should be delayed, if other variables with negative reduced
2111 * costs have already been found in the current pricing round.
2112 * Variables may be declared to be "removable" in the SCIPcreateVar() call. This means that SCIP may remove the variable
2113 * from the LP if it was inactive (i.e., sitting at zero) for a number of LP solves. Nevertheless, after the removal of the
2114 * column from the LP, the variable still exists, and SCIP can calculate reduced costs and add it to the LP again if
2115 * necessary.
2116 * \n
2117 * If the PRICER_DELAY flag is set to TRUE (which is the common setting), all those existing variables with negative reduced costs
2118 * are added to the LP, and the LP is resolved before the pricer is called. Thus, the pricer can assume that all existing variables
2119 * have non-negative reduced costs if the \ref PRICERREDCOST method is called or non-positive Farkas value if the \ref PRICERFARKAS
2120 * method is called.
2121 * \n
2122 * In some applications, this inner pricing loop on the already existing variables can significantly slow down the solving process,
2123 * since it may lead to the addition of only very few variables in each pricing round. If this is an issue in your application,
2124 * you should consider setting the PRICER_DELAY flag to FALSE. You must, however, be aware of the fact that there may be already
2125 * existing variables with negative reduced costs. For example, this may lead to the issue that your pricer generates the same
2126 * variable twice. In some models, this is not critical because an optimal solution would choose only one of the two identical
2127 * variables anyway, but for other models this can lead to wrong results because the duplication of a variable essentially doubles
2128 * the upper bound of the variable.
2129 *
2130 *
2131 * @section PRICER_DATA Pricer Data
2132 *
2133 * Below the header "Data structures" you can find a struct which is called "struct SCIP_PricerData".
2134 * In this data structure, you can store the data of your pricer. For example, it may be convenient to store pointers to the
2135 * constraints of the problem instance here, because the pricer has to add variables to those constraints.
2136 * If you are using C++, you can add pricer data, as usual, as object variables to your class.
2137 * \n
2138 * Defining pricer data is optional. You can leave the struct empty.
2139 *
2140 *
2141 * @section PRICER_INTERFACE Interface Methods
2142 *
2143 * At the bottom of "pricer_mypricer.c" you can find the interface method SCIPincludePricerMypricer(), which also appears in "pricer_mypricer.h".
2144 * 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
2145 * be generated by this pricer.
2146 *
2147 * This method only has to be adjusted slightly.
2148 * It is responsible for notifying SCIP of the presence of the pricer. For this, you can either call SCIPincludePricer(),
2149 * or SCIPincludePricerBasic() since SCIP version 3.0. In the latter variant, \ref PRICER_ADDITIONALCALLBACKS "additional callbacks"
2150 * must be added via setter functions as, e.g., SCIPsetPricerCopy(). We recommend this latter variant because
2151 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2152 * variant must be manually adjusted with every SCIP release containing new callbacks for pricers in order to compile.
2153 *
2154 *
2155 * In addition, the pricer has to be activated before the solution process starts, like it is done
2156 * in the pricer of the Coloring application (applications/Coloring/src/reader_col.c) by calling
2157 * \code
2158 * SCIP_CALL( SCIPactivatePricer(scip, SCIPfindPricer(scip, "coloring")) );
2159 * \endcode
2160 *
2161 * If you are using pricer data, you have to allocate the memory for the data at this point.
2162 * You can do this by calling:
2163 * \code
2164 * SCIP_CALL( SCIPallocBlockMemory(scip, &pricerdata) );
2165 * \endcode
2166 * You also have to initialize the fields in struct SCIP_PricerData afterwards.
2167 *
2168 * You may also add user parameters for your pricer, see the method SCIPincludePricerColoring() in the pricer of the Coloring application
2169 * for an example of how to add user parameters.
2170 *
2171 *
2172 * @section PRICER_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Pricer
2173 *
2174 * The fundamental callback methods have to be implemented in order to obtain an operational algorithm.
2175 * They are passed together with the pricer itself to SCIP using SCIPincludePricer() or SCIPincludePricerBasic(),
2176 * see @ref PRICER_INTERFACE.
2177 *
2178 * In the case of a pricer, there are two fundamental callback methods, namely the @ref PRICERREDCOST and the
2179 * @ref PRICERFARKAS callbacks, which both search for new variables and add them to the problem.
2180 * These methods have to be implemented for every pricer; the other callback methods are optional.
2181 * In the C++ wrapper class scip::ObjPricer, the scip_redcost() method (which corresponds to the PRICERREDCOST callback)
2182 * is a virtual abstract member function. You have to implement it in order to be able to construct an object of your
2183 * pricer class.
2184 *
2185 * Additional documentation for the callback methods can be found in type_pricer.h.
2186 *
2187 * @subsection PRICERREDCOST
2188 *
2189 * The PRICERREDCOST callback is called inside the price-and-cut loop of the subproblem solving process if the current LP relaxation
2190 * is feasible.
2191 * It should search for additional variables that can contribute to improve the current LP's solution value.
2192 * In standard branch-and-price, these are variables with negative dual feasibility, that is negative
2193 * reduced costs for non-negative variables, positive reduced costs for non-positive variables,
2194 * and non-zero reduced costs for variables that can be negative and positive.
2195 *
2196 * Whenever the pricer finds a variable with negative dual feasibility, it should call SCIPcreateVar()
2197 * and SCIPaddPricedVar() to add the variable to the problem. Furthermore, it should call the appropriate
2198 * methods of the constraint handlers to add the necessary variable entries to the constraints, see pub_cons.h.
2199 *
2200 * In the usual case that the pricer either adds a new variable or ensures that there are no further variables with negative dual feasibility,
2201 * the result pointer should be set to SCIP_SUCCESS. Only if the pricer aborts pricing without creating a new variable, but
2202 * there might exist additional variables with negative dual feasibility, the result pointer should be set to SCIP_DIDNOTRUN.
2203 * In this case, which sometimes is referred to as "early branching", the LP solution will not be used as a lower bound.
2204 * The pricer can, however, store a valid lower bound in the <code>lowerbound</code> pointer.
2205 *
2206 * Pricers usually need the dual LP solution as input for the pricing algorithm.
2207 * Since SCIP does not know the semantics of the individual constraints in the problem, the dual solution
2208 * has to be provided by the constraint handlers.
2209 * For example, the \ref cons_setppc.h "setppc constraint handler", which deals with set partitioning, packing, and covering constraints, provides
2210 * the method SCIPgetDualsolSetppc() to access the dual solution value for a single constraint.
2211 * Similarly, the dual solution of a linear constraint can be queried with the method SCIPgetDualsolLinear() of cons_linear.h.
2212 * The reduced costs of the existing variables can be accessed with the method SCIPgetVarRedcost().
2213 *
2214 * @subsection PRICERFARKAS
2215 *
2216 * If the current LP relaxation is infeasible, it is the task of the pricer to generate additional variables that can
2217 * potentially render the LP feasible again. In standard branch-and-price, these are variables with positive Farkas values,
2218 * and the PRICERFARKAS method should identify those variables.
2219 *
2220 * If the LP was proven to be infeasible, we have an infeasibility proof by the dual Farkas multipliers \f$y\f$.
2221 * 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
2222 * by the sides of the LP rows and the sign of \f$y\f$:
2223 * - if \f$y_i\f$ is positive, \f$b_i\f$ is the left hand side of the row,
2224 * - if \f$y_i\f$ is negative, \f$b_i\f$ is the right hand side of the row.
2225 *
2226 * \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$,
2227 * especially by the (for this inequality least infeasible solution) \f$x'\f$ defined by
2228 * - \f$x'_i := ub_i\f$, if \f$y^T A_i \ge 0\f$
2229 * - \f$x'_i := lb_i\f$, if \f$y^T A_i < 0\f$.
2230 * 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$.
2231 *
2232 * To apply Farkas pricing, the pricer needs to know the Farkas values of the constraints. Like the dual solution values for
2233 * feasible LP solutions, the dual Farkas values for infeasible solutions can be obtained by constraint handler interface
2234 * methods such as the SCIPgetDualfarkasLinear() method of the linear constraint handler.
2235 * The Farkas values for the bounds of the variables can be accessed with SCIPgetVarFarkasCoef().
2236 *
2237 * It is useful to note that Farkas pricing is the same as the regular pricing with a zero objective function.
2238 * Therefore, a typical implementation of a pricer would consist of a generic pricing algorithm that gets a dual solution and an
2239 * objective function vector as input and generates variables by calling SCIPcreateVar() and SCIPaddPricedVar().
2240 * The PRICERREDCOST callback would call this function with the regular objective function and the regular dual solution vector,
2241 * while the PRICERFARKAS callback would call this function with a zero objective function and the Farkas vector.
2242 * From a practical point of view, it is usually the simplest approach to provide just one Boolean flag to the generic pricing
2243 * algorithm in order to identify whether it is reduced cost or Farkas pricing. Then, the algorithm would just call the appropriate
2244 * methods to access the dual solution or objective function, depending on the Boolean flag.
2245 *
2246 * @section PRICER_ADDITIONALCALLBACKS Additional Callback Methods of a Pricer
2247 *
2248 * The additional callback methods do not need to be implemented in every case.
2249 * However, some of them have to be implemented for most applications. They can either be passed directly with
2250 * SCIPincludePricer() to SCIP or via specific <b>setter functions</b> after a call of SCIPincludePricerBasic(),
2251 * see also @ref PRICER_INTERFACE.
2252 *
2253 * @subsection PRICERFREE
2254 *
2255 * If you are using pricer data, you have to implement this method in order to free the pricer data.
2256 * This can be done by the procedure described in stp/src/pricer_stp.c,
2257 * see https://scipjack.zib.de/.
2258 *
2259 * If you have allocated memory for fields in your pricer data, remember to free this memory
2260 * before freeing the pricer data itself.
2261 * If you are using the C++ wrapper class, this method is not available.
2262 * Instead, just use the destructor of your class to free the member variables of your class.
2263 *
2264 * @subsection PRICERCOPY
2265 *
2266 * The PRICERCOPY callback is executed when the SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
2267 * callback as <code>NULL</code> the user disables the inclusion of the pricer into all copied SCIP
2268 * instances. This means that primal heuristics will work on a sub-SCIP that contains only a part of the variables
2269 * and no variables are priced in during the solving process of the sub-SCIP. Therefore, primal solutions found in the
2270 * copied problem are typically still valid for the original problem and used for its solving process,
2271 * but dual reductions cannot be transferred to the original problem.
2272 *
2273 * <b>Note:</b> If you implement this callback, be careful when setting the valid pointer. The valid pointer should be
2274 * set to TRUE if (and only if!) you can make sure that all necessary data of the pricer are copied
2275 * correctly. If the complete problem is validly copied, i.e. if the copy methods of all problem defining plugins
2276 * (constraint handlers and pricers) return <code>*valid = TRUE</code>, then dual reductions found for the copied problem can be
2277 * transferred to the original SCIP instance. Thus, if the valid pointer is wrongly set to TRUE, it might happen that
2278 * optimal solutions are cut off.
2279 *
2280 * @subsection PRICERINIT
2281 *
2282 * The PRICERINIT callback is executed after the problem is transformed.
2283 * The pricer may, e.g., use this call to replace the original constraints stored in its pricer data by transformed
2284 * constraints, or to initialize other elements of its pricer data.
2285 *
2286 * @subsection PRICEREXIT
2287 *
2288 * The PRICEREXIT callback is executed before the transformed problem is freed.
2289 * In this method, the pricer should free all resources that have been allocated for the solving process in PRICERINIT.
2290 *
2291 * @subsection PRICERINITSOL
2292 *
2293 * The PRICERINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to begin.
2294 * The pricer may use this call to initialize its branch-and-bound specific data.
2295 *
2296 * @subsection PRICEREXITSOL
2297 *
2298 * The PRICEREXITSOL callback is executed before the branch-and-bound process is freed.
2299 * The pricer should use this call to clean up its branch-and-bound data, which was allocated in PRICERINITSOL.
2300 *
2301 * @section PRICER_REMARKS Further remarks
2302 *
2303 * 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".
2304 * Otherwise, SCIP will use its default branching rules, if necessary (which all branch on variables). This
2305 * could disturb the pricing problem or branching might not even be possible, e.g., if all variables created thus far have already been fixed.
2306 *
2307 * Note that if the original problem is a maximization problem, SCIP will transform the problem into a minimization
2308 * problem by multiplying the objective function by -1. The pricer has to take care of this by multiplying
2309 * the original objective function value of all variables created during the solving process by -1.
2310 *
2311 * In some cases, bounds on variables are implicitly enforced by constraints of the problem and the objective function.
2312 * 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
2313 * care about the corresponding dual values.
2314 * We call these bounds lazy bounds, they may be set by SCIPchgVarLbLazy() and SCIPchgVarUbLazy() for upper or lower bounds, respectively.
2315 * If the lazy bound equals the local bound, the corresponding bound is not put into the LP.
2316 * In diving mode, lazy bounds are explicitly put into the LP, because changing the objective (which is only possible in diving)
2317 * might reverse the implicitly given bounds. When diving is finished, the bounds are again removed from the LP.
2318 */
2319
2320/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2321
2322/**@page PRESOL How to add presolvers
2323 *
2324 * Presolvers are used to reduce the size of the model by removing irrelevant information like redundant constraints,
2325 * to strengthen the LP relaxation by exploiting integrality information, and to extract useful information in the
2326 * presolving step.
2327 * Constraint based presolving is done in the CONSPRESOL callback methods of the constraint handlers, see \ref CONSPRESOL.
2328 * Some propagation steps can already be applied in presolving via the PROPRESOL callback methods of propagators, see \ref PROPPRESOL.
2329 * The presolver plugins complement these by additional, usually optimality based, presolving reductions.
2330 * \n
2331 * A complete list of all presolvers contained in this release can be found \ref PRESOLVERS "here".
2332 *
2333 * We now explain how users can add their own presolvers.
2334 * Take the trivial presolver (src/scip/presol_trivial.c) as an example.
2335 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjPresol wrapper
2336 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_PRESOL... callback methods.
2337 *
2338 * Additional documentation for the callback methods of a presolver, in particular for their input parameters,
2339 * can be found in the file type_presol.h.
2340 *
2341 * Here is what you have to do to implement a presolver:
2342 * -# Copy the template files src/scip/presol_xyz.c and src/scip/presol_xyz.h into files named "presol_mypresolver.c"
2343 * and "presol_mypresolver.h".
2344 * \n
2345 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2346 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2347 * -# Use `SCIPincludePresolMypresolver()` in order to include the presolver into your SCIP instance,
2348 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2349 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2350 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypresolver".
2351 * -# Adjust the properties of the presolver (see \ref PRESOL_PROPERTIES).
2352 * -# Define the presolver data (see \ref PRESOL_DATA). This is optional.
2353 * -# Implement the interface methods (see \ref PRESOL_INTERFACE).
2354 * -# Implement the fundamental callback methods (see \ref PRESOL_FUNDAMENTALCALLBACKS).
2355 * -# Implement the additional callback methods (see \ref PRESOL_ADDITIONALCALLBACKS). This is optional.
2356 *
2357 *
2358 * @section PRESOL_PROPERTIES Properties of a Presolver
2359 *
2360 * At the top of the new file "presol_mypresolver.c", you can find the presolver properties.
2361 * These are given as compiler defines.
2362 * In the C++ wrapper class, you have to provide the presolver properties by calling the constructor
2363 * of the abstract base class scip::ObjPresol from within your constructor.
2364 * The properties you have to set have the following meaning:
2365 *
2366 * \par PRESOL_NAME: the name of the presolver.
2367 * This name is used in the interactive shell to address the presolver.
2368 * Additionally, if you are searching for a presolver with SCIPfindPresol(), this name is looked up.
2369 * Names have to be <b>unique</b>: no two presolvers may have the same name.
2370 *
2371 * \par PRESOL_DESC: the description of the presolver.
2372 * This string is printed as a description of the presolver in the interactive shell.
2373 *
2374 * \par PRESOL_TIMING: the default timing of the presolver.
2375 * There are three presolving timings: FAST, MEDIUM, and EXHAUSTIVE.
2376 * Every presolving round starts with the FAST presolvers. MEDIUM presolvers are only called, if FAST presolvers did not find
2377 * enough reductions in this round so far, and EXHAUSTIVE presolving steps are only performed if all presolvers called before
2378 * in this round were unsuccessful.
2379 * Presolvers should be assigned a timing based on how expensive they are, e.g., presolvers that provide fast algorithms that
2380 * usually have a high impact (i.e., remove lots of variables or tighten bounds of many variables) should have a timing FAST.
2381 * If a presolver implements different algorithms of different complexity, it may also get multiple timings and check the timing
2382 * internally in the \ref PRESOLEXEC callback to decide which algorithms to run.
2383 *
2384 * \par PRESOL_PRIORITY: the priority of the presolver.
2385 * Within a presolving round, when calling all presolvers and presolving methods of propagators and constraint handlers
2386 * with a given timing, those are called in
2387 * a predefined order, which is given by the priorities of the presolvers and the check priorities of the
2388 * constraint handlers, see \ref CONS_PROPERTIES.
2389 * First, the presolvers with non-negative priority are called in the order of decreasing priority.
2390 * Next, the presolving methods of the different constraint handlers are called in the order of decreasing check
2391 * priority.
2392 * Finally, the presolvers with negative priority are called in the order of decreasing priority.
2393 * \n
2394 * Again, presolvers that provide fast algorithms that usually have a high impact (i.e., remove lots of variables or tighten
2395 * bounds of many variables) should have a high priority.
2396 * An easy way to list the timings and
2397 * priorities of all presolvers, propagators, and constraint handlers is to type "display presolvers", "display propagators",
2398 * and "display conshdlrs" in the interactive shell of SCIP.
2399 *
2400 * \par PRESOL_MAXROUNDS: the default maximal number of rounds the presolver participates in.
2401 * The presolving is conducted in rounds: the presolvers and presolving methods of the constraint handlers
2402 * are called iteratively until no more reductions have been found or some other abort criterion applies.
2403 * The "maxrounds" parameter of a presolver imposes a limit on the number of presolving rounds in which the
2404 * presolver is called. The PRESOL_MAXROUNDS property specifies the default value for this parameter.
2405 * A value of -1 represents an unlimited number of rounds.
2406 *
2407 *
2408 * @section PRESOL_DATA Presolver Data
2409 *
2410 * Below the header "Data structures" you can find a struct which is called "struct SCIP_PresolData".
2411 * In this data structure, you can store the data of your presolver. For example, you should store the adjustable parameters
2412 * of the presolver in this data structure.
2413 * If you are using C++, you can add presolver data as usual as object variables to your class.
2414 * \n
2415 * Defining presolver data is optional. You can leave this struct empty.
2416 *
2417 *
2418 * @section PRESOL_INTERFACE Interface Methods
2419 *
2420 * At the bottom of "presol_mypresolver.c", you can find the interface method SCIPincludePresolMypresolver(),
2421 * which also appears in "presol_mypresolver.h"
2422 * SCIPincludePresolMypresolver() is called by the user, if (s)he wants to include the presolver,
2423 * i.e., if (s)he wants to use the presolver in his/her application.
2424 *
2425 * This method only has to be adjusted slightly.
2426 * It is responsible for notifying SCIP of the presence of the presolver. For this, you can either call SCIPincludePresol(),
2427 * or SCIPincludePresolBasic() since SCIP version 3.0. In the latter variant, \ref PRESOL_ADDITIONALCALLBACKS "additional callbacks"
2428 * must be added via setter functions as, e.g., SCIPsetPresolCopy(). We recommend this latter variant because
2429 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2430 * variant must be manually adjusted with every SCIP release containing new callbacks for presolvers in order to compile.
2431 *
2432 * If you are using presolver data, you have to allocate the memory for the data at this point.
2433 * You can do this by calling:
2434 * \code
2435 * SCIP_CALL( SCIPallocBlockMemory(scip, &presoldata) );
2436 * \endcode
2437 * You also have to initialize the fields in struct SCIP_PresolData afterwards. For freeing the
2438 * presolver data, see \ref PRESOLFREE.
2439 *
2440 * You may also add user parameters for your presolver, see \ref PARAM for how to add user parameters and
2441 * the method SCIPincludePresolTrivial() in src/scip/presol_trivial.c for an example.
2442 *
2443 *
2444 * @section PRESOL_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Presolver
2445 *
2446 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2447 * an operational algorithm.
2448 * They are passed together with the presolver itself to SCIP using SCIPincludePresol() or SCIPincludePresolBasic(),
2449 * see @ref PRESOL_INTERFACE.
2450 *
2451 * Presolver plugins have only one fundamental callback method, namely the @ref PRESOLEXEC method.
2452 * This method has to be implemented for every presolver; the other callback methods are optional.
2453 * In the C++ wrapper class scip::ObjPresol, the scip_exec() method (which corresponds to the PRESOLEXEC callback) is a virtual
2454 * abstract member function.
2455 * You have to implement it in order to be able to construct an object of your presolver class.
2456 *
2457 * Additional documentation for the callback methods, in particular to their input parameters,
2458 * can be found in type_presol.h.
2459 *
2460 * @subsection PRESOLEXEC
2461 *
2462 * The PRESOLEXEC callback is called inside the presolving loop and should perform the actual presolving reductions.
2463 * It should inspect the problem instance at hand and simplify it by tightening bounds of variables, aggregating or fixing
2464 * variables, changing the type of variables, modifying the graph that represents the instance of your application, and
2465 * the like.
2466 *
2467 * Typical methods called by a presolver are, for example, SCIPchgVarType(), SCIPfixVar(), SCIPaggregateVars(), SCIPtightenVarLb(),
2468 * and SCIPtightenVarUb().
2469 *
2470 *
2471 * @section PRESOL_ADDITIONALCALLBACKS Additional Callback Methods of a Presolver
2472 *
2473 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2474 * implemented for most applications, they can be used, for example, to initialize and free private data.
2475 * Additional callbacks can either be passed directly with SCIPincludePresol() to SCIP or via specific
2476 * <b>setter functions</b> after a call of SCIPincludePresolBasic(), see also @ref PRESOL_INTERFACE.
2477 *
2478 * @subsection PRESOLFREE
2479 *
2480 * 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.
2481 * This can be done by the following procedure:
2482 *
2483 * @refsnippet{src/scip/presol_boundshift.c,SnippetPresolFreeBoundshift}
2484 *
2485 * If you have allocated memory for fields in your presolver data, remember to free this memory
2486 * before freeing the presolver data itself.
2487 * If you are using the C++ wrapper class, this method is not available.
2488 * Instead, just use the destructor of your class to free the member variables of your class.
2489 *
2490 * @subsection PRESOLINIT
2491 *
2492 * The PRESOLINIT callback is executed after the problem is transformed.
2493 * The presolver may, e.g., use this call to initialize its presolver data.
2494 * The difference between the original and the transformed problem is explained in
2495 * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
2496 *
2497 * @subsection PRESOLCOPY
2498 *
2499 * The PRESOLCOPY callback is executed when a SCIP instance is copied, e.g. to
2500 * solve a sub-SCIP. By
2501 * defining this callback as
2502 * <code>NULL</code> the user disables the execution of the specified
2503 * presolver for all copied SCIP instances. This may deteriorate the performance
2504 * of primal heuristics using sub-SCIPs.
2505 *
2506 * @subsection PRESOLEXIT
2507 *
2508 * The PRESOLEXIT callback is executed before the transformed problem is freed.
2509 * In this method, the presolver should free all resources that have been allocated for the solving process in PRESOLINIT.
2510 *
2511 * @subsection PRESOLINITPRE
2512 *
2513 * The PRESOLINITPRE callback is executed when the presolving is about to begin.
2514 * The presolver may use this call to initialize its presolving data which only need to exist during the presolving stage.
2515 *
2516 * @subsection PRESOLEXITPRE
2517 *
2518 * The PRESOLEXITPRE callback is executed after presolving finishes and before the branch-and-bound process begins.
2519 * The presolver should use this call to clean up its presolving data, which was allocated in PRESOLINITPRE.
2520 */
2521
2522/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2523
2524/**@page SEPA How to add separators
2525 *
2526 * Separators are used to generate cutting planes that strengthen the LP relaxation of the problem formulation, but are
2527 * not required for a completeness and correctness of the model.
2528 * In contrast, constraint-based cutting planes, the second type of cutting planes in SCIP, are separated in the CONSSEPALP and
2529 * CONSSEPASOL callback methods of the constraint handlers, see \ref CONSSEPALP and \ref CONSSEPASOL. These cuts are
2530 * valid inequalities or even facets of the polyhedron described by a single constraint or a subset of the constraints of
2531 * a single constraint class. See also
2532 * "When should I implement a constraint handler, when should I implement a separator?" on \ref FAQ.
2533 * \n
2534 * A complete list of all separators contained in this release can be found \ref SEPARATORS "here".
2535 *
2536 * We now explain how users can add their own separators.
2537 * Take the separator for the class of Gomory mixed integer inequalities (src/scip/sepa_gomory.c) as an example.
2538 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjSepa wrapper
2539 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_SEPA... callback methods.
2540 *
2541 * Additional documentation for the callback methods of a separator, in particular for the input parameters,
2542 * can be found in the file type_sepa.h.
2543 *
2544 * Here is what you have to do to implement a separator:
2545 * -# Copy the template files src/scip/sepa_xyz.c and src/scip/sepa_xyz.h into files "sepa_myseparator.c"
2546 * and "sepa_myseparator.h".
2547 \n
2548 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2549 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2550 * -# Use `SCIPincludeSepaMyseparator()` in order to include the separator into your SCIP instance,
2551 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2552 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2553 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myseparator".
2554 * -# Adjust the properties of the separator (see \ref SEPA_PROPERTIES).
2555 * -# Define the separator data (see \ref SEPA_DATA). This is optional.
2556 * -# Implement the interface methods (see \ref SEPA_INTERFACE).
2557 * -# Implement the fundamental callback methods (see \ref SEPA_FUNDAMENTALCALLBACKS).
2558 * -# Implement the additional callback methods (see \ref SEPA_ADDITIONALCALLBACKS). This is optional.
2559 *
2560 *
2561 * @section SEPA_PROPERTIES Properties of a Separator
2562 *
2563 * At the top of the new file "sepa_myseparator.c", you can find the separator properties.
2564 * These are given as compiler defines.
2565 * In the C++ wrapper class, you have to provide the separator properties by calling the constructor
2566 * of the abstract base class scip::ObjSepa from within your constructor.
2567 * The properties you have to set have the following meaning:
2568 *
2569 * \par SEPA_NAME: the name of the separator.
2570 * This name is used in the interactive shell to address the separator.
2571 * Additionally, if you are searching for a separator with SCIPfindSepa(), this name is looked up.
2572 * Names have to be unique: no two separators may have the same name.
2573 *
2574 * \par SEPA_DESC: the description of the separator.
2575 * This string is printed as a description of the separator in the interactive shell.
2576 *
2577 * \par SEPA_PRIORITY: the priority of the separator.
2578 * In each separation round during the price-and-cut loop of the subproblem processing or the separation loop
2579 * of the primal solution separation, the separators and separation methods of the constraint handlers are called in
2580 * a predefined order, which is given by the priorities of the separators and the separation priorities
2581 * of the constraint handlers (see \ref CONS_PROPERTIES).
2582 * First, the separators with non-negative priority are called in the order of decreasing priority.
2583 * Next, the separation methods of the constraint handlers are called in the order of decreasing separation
2584 * priority.
2585 * Finally, the separators with negative priority are called in the order of decreasing priority. An easy way to list the
2586 * priorities of all separators and constraint handlers is to type "display separators" and "display conshdlrs" in
2587 * the interactive shell.
2588 * \n
2589 * The priority of the separator should be set according to the complexity of the cut separation algorithm and the
2590 * impact of the resulting cuts: separators that provide fast algorithms that usually have a high impact (i.e., cut off
2591 * a large portion of the LP relaxation) should have a high priority.
2592 * See \ref SEPAEXECLP and \ref SEPAEXECSOL for further details of the separation callbacks.
2593 *
2594 * \par SEPA_FREQ: the default frequency for separating cuts.
2595 * The frequency defines the depth levels at which the separation methods \ref SEPAEXECLP and \ref SEPAEXECSOL are called.
2596 * For example, a frequency of 7 means, that the separation callback is executed for subproblems that are in depth
2597 * 0, 7, 14, ... of the branching tree. A frequency of 0 means, that the separation method is only called at the root node.
2598 * A frequency of -1 disables the separator.
2599 * \n
2600 * The frequency can be adjusted by the user. This property of the separator only defines the default value of the frequency.
2601 * If you want to have a more flexible control of when to execute the separation algorithm, you have to assign
2602 * a frequency of 1 and implement a check at the beginning of your separation methods whether you really want to execute
2603 * the separation or not. If you do not want to execute it, set the result code of
2604 * \ref SEPAEXECLP and \ref SEPAEXECSOL to SCIP_DIDNOTRUN.
2605 *
2606 * \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.
2607 * At the current branch-and-bound node, the relative distance from its dual bound (local dual bound)
2608 * to the primal bound compared to the best node's dual bound (global dual bound) is considered. The separation method
2609 * of the separator will only be applied at the current node if this relative distance does not exceed SEPA_MAXBOUNDDIST.
2610 * \n
2611 * For example, if the global dual bound is 50 and the primal bound is 60, SEPA_MAXBOUNDDIST = 0.25 means that separation
2612 * 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
2613 * than or equal to 52.5.
2614 * \n
2615 * In particular, the values 0.0 and 1.0 mean that separation is applied at the current best node only or at all
2616 * nodes, respectively. Since separation seems to be most important to apply at nodes that define to the global
2617 * dual bound, 0.0 is probably a good choice for SEPA_MAXBOUNDDIST.
2618 * Note that separators with a frequency of SEPA_FREQ = 0 are only applied at the root node.
2619 * Obviously, at the root node the local dual bound is equal to the global dual bound and thus, the separator is called
2620 * for any value of SEPA_MAXBOUNDDIST.
2621 *
2622 * \par SEPA_USESSUBSCIP: Does the separator use a secondary SCIP instance?
2623 * Some heuristics and separators solve MIPs or SAT problems and use a secondary SCIP instance. Examples are
2624 * Large Neighborhood Search heuristics such as RINS and Local Branching or the CGMIP separator. To avoid recursion,
2625 * these plugins usually deactivate all other plugins that solve MIPs. If a separator uses a secondary SCIP instance,
2626 * this parameter has to be TRUE and it is recommended to call SCIPsetSubscipsOff() for the secondary SCIP instance.
2627 *
2628 * \par SEPA_DELAY: the default for whether the separation method should be delayed, if other separators or constraint handlers found cuts.
2629 * If the separator's separation method is marked to be delayed, it is only executed after no other separator
2630 * or constraint handler found a cut during the price-and-cut loop.
2631 * If the separation method of the separator is very expensive, you may want to mark it to be delayed until all cheap
2632 * separation methods have been executed.
2633 *
2634 * @section SEPA_DATA Separator Data
2635 *
2636 * Below the header "Data structures" you can find a struct which is called "struct SCIP_SepaData".
2637 * In this data structure, you can store the data of your separator. For example, you should store the adjustable
2638 * parameters of the separator in this data structure. In a separator, user parameters for the maximal number of
2639 * separation rounds per node and for the maximal number of cuts separated per separation round might be useful.
2640 * If you are using C++, you can add separator data as usual as object variables to your class.
2641 * \n
2642 * Defining separator data is optional. You can leave the struct empty.
2643 *
2644 * @section SEPA_INTERFACE Interface Methods
2645 *
2646 * At the bottom of "sepa_myseparator.c", you can find the interface method SCIPincludeSepaMyseparator(),
2647 * which also appears in "sepa_myseparator.h"
2648 * SCIPincludeSepaMyseparator() is called by the user, if (s)he wants to include the separator,
2649 * i.e., if (s)he wants to use the separator in his/her application.
2650 *
2651 * This method only has to be adjusted slightly.
2652 * It is responsible for notifying SCIP of the presence of the separator. For this, you can either call SCIPincludeSepa(),
2653 * or SCIPincludeSepaBasic() since SCIP version 3.0. In the latter variant, \ref SEPA_ADDITIONALCALLBACKS "additional callbacks"
2654 * must be added via setter functions as, e.g., SCIPsetSepaCopy(). We recommend this latter variant because
2655 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2656 * variant must be manually adjusted with every SCIP release containing new callbacks for separators in order to compile.
2657 *
2658 * If you are using separator data, you have to allocate the memory
2659 * for the data at this point. You can do this by calling:
2660 * \code
2661 * SCIP_CALL( SCIPallocBlockMemory(scip, &sepadata) );
2662 * \endcode
2663 * You also have to initialize the fields in "struct SCIP_SepaData" afterwards. For freeing the
2664 * separator data, see \ref SEPAFREE.
2665 *
2666 * You may also add user parameters for your separator, see \ref PARAM for how to add user parameters and
2667 * the method SCIPincludeSepaGomory() in src/scip/sepa_gomory.c for an example.
2668 *
2669 *
2670 * @section SEPA_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Separator
2671 *
2672 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2673 * an operational algorithm.
2674 * They are passed together with the separator itself to SCIP using SCIPincludeSepa() or SCIPincludeSepaBasic(),
2675 * see @ref SEPA_INTERFACE.
2676 *
2677 * Separator plugins have two callbacks, @ref SEPAEXECLP and @ref SEPAEXECSOL, of which at least one must be implemented.
2678 *
2679 * Additional documentation for the callback methods, in particular to their input parameters,
2680 * can be found in type_sepa.h.
2681 *
2682 * @subsection SEPAEXECLP
2683 *
2684 * The SEPAEXECLP callback is executed during the price-and-cut loop of the subproblem processing.
2685 * It should try to generate general purpose cutting planes in order to separate the current LP solution.
2686 * The method is called in the LP solution loop, which means that a valid LP solution exists.
2687 *
2688 * Usually, the callback searches and produces cuts, that are added with a call to SCIPaddCut().
2689 * If the cut should be added to the global cut pool, it calls SCIPaddPoolCut().
2690 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
2691 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
2692 * In addition to LP rows, the callback may also produce domain reductions or add additional constraints.
2693 *
2694 * Overall, the SEPAEXECLP callback has the following options, which is indicated by the possible return values of
2695 * the 'result' variable (see type_sepa.h):
2696 * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
2697 * - adding an additional constraint (result SCIP_CONSADDED)
2698 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
2699 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
2700 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
2701 * (result SCIP_DIDNOTFIND)
2702 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
2703 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
2704 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
2705 *
2706 * @subsection SEPAEXECSOL
2707 *
2708 * The SEPAEXECSOL callback is executed during the separation loop on arbitrary primal solutions.
2709 * It should try to generate general purpose cutting planes in order to separate the given primal solution.
2710 * The method is not called in the LP solution loop, which means that there is no valid LP solution.
2711 *
2712 * In the standard SCIP environment, the SEPAEXECSOL callback is not used because only LP solutions are
2713 * separated. The SEPAEXECSOL callback provides means to support external relaxation handlers like semidefinite
2714 * relaxations that want to separate an intermediate primal solution vector. Thus, if you do not want to support
2715 * such external plugins, you do not need to implement this callback method.
2716 *
2717 * Usually, the callback searches and produces cuts, that are added with a call to SCIPaddCut().
2718 * If the cut should be added to the global cut pool, it calls SCIPaddPoolCut().
2719 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
2720 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
2721 * In addition to LP rows, the callback may also produce domain reductions or add other constraints.
2722 *
2723 * Overall, the SEPAEXECSOL callback has the following options, which is indicated by the possible return values of
2724 * the 'result' variable (see type_sepa.h):
2725 * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
2726 * - adding an additional constraint (result SCIP_CONSADDED)
2727 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
2728 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
2729 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
2730 * (result SCIP_DIDNOTFIND)
2731 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
2732 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
2733 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
2734 *
2735 *
2736 * @section SEPA_ADDITIONALCALLBACKS Additional Callback Methods of a Separator
2737 *
2738 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2739 * implemented for most applications, they can be used, for example, to initialize and free private data.
2740 * Additional callbacks can either be passed directly with SCIPincludeSepa() to SCIP or via specific
2741 * <b>setter functions</b> after a call of SCIPincludeSepaBasic(), see also @ref SEPA_INTERFACE.
2742 *
2743 * @subsection SEPAFREE
2744 *
2745 * If you are using separator data (see \ref SEPA_DATA and \ref SEPA_INTERFACE), you have to implement this method
2746 * in order to free the separator data. This can be done by the following procedure:
2747 *
2748 * @refsnippet{src/scip/sepa_gomory.c,SnippetSepaFreeGomory}
2749 *
2750 * If you have allocated memory for fields in your separator data, remember to free this memory
2751 * before freeing the separator data itself.
2752 * If you are using the C++ wrapper class, this method is not available.
2753 * Instead, just use the destructor of your class to free the member variables of your class.
2754 *
2755 * @subsection SEPACOPY
2756 *
2757 * The SEPACOPY callback is executed when a SCIP instance is copied, e.g. to
2758 * solve a sub-SCIP. By
2759 * defining this callback as
2760 * <code>NULL</code> the user disables the execution of the specified
2761 * separator for all copied SCIP instances. This may deteriorate the performance
2762 * of primal heuristics using sub-SCIPs.
2763 *
2764 * @subsection SEPAINIT
2765 *
2766 * The SEPAINIT callback is executed after the problem is transformed.
2767 * The separator may, e.g., use this call to initialize its separator data.
2768 * The difference between the original and the transformed problem is explained in
2769 * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
2770 *
2771 * @subsection SEPAEXIT
2772 *
2773 * The SEPAEXIT callback is executed before the transformed problem is freed.
2774 * In this method, the separator should free all resources that have been allocated for the solving process in SEPAINIT.
2775 *
2776 * @subsection SEPAINITSOL
2777 *
2778 * The SEPAINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
2779 * begin. The separator may use this call to initialize its branch-and-bound specific data.
2780 *
2781 * @subsection SEPAEXITSOL
2782 *
2783 * The SEPAEXITSOL callback is executed before the branch-and-bound process is freed. The separator should use this call
2784 * to clean up its branch-and-bound data, in particular to release all LP rows that it has created or captured.
2785 */
2786
2787/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2788
2789/**@page PROP How to add propagators
2790 *
2791 * Propagators are used to tighten the domains of the variables. Like for cutting planes, there are two different types
2792 * of domain propagations. Constraint based (primal) domain propagation algorithms are part of the corresponding
2793 * constraint handlers, see \ref CONSPROP. In contrast, domain propagators usually provide dual propagations, i.e.,
2794 * propagations that can be applied using the objective function and the current best known primal solution. This
2795 * section deals with such propagators.
2796 *
2797 * A complete list of all propagators contained in this release can be found \ref PROPAGATORS "here".
2798 *
2799 * We now explain how users can add their own propagators. Take the pseudo objective function propagator
2800 * (src/scip/prop_pseudoobj.c) as an example. As all other default plugins, it is written in C. C++ users can easily
2801 * adapt the code by using the scip::ObjProp wrapper base class and implement the @c scip_...() virtual methods instead
2802 * of the @c SCIP_DECL_PROP... callback methods.
2803 *
2804 * Additional documentation for the callback methods of a propagator can be found in the file type_prop.h.
2805 *
2806 * Here is what you have to do to implement a propagator:
2807 * -# Copy the template files src/scip/prop_xyz.c and src/scip/prop_xyz.h into files named "prop_mypropagator.c"
2808 * and "prop_mypropagator.h".
2809 * \n
2810 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2811 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2812 * -# Use `SCIPincludePropMypropagator()` in order to include the propagator into your SCIP instance,
2813 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2814 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2815 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypropagator".
2816 * -# Adjust the properties of the propagator (see \ref PROP_PROPERTIES).
2817 * -# Define the propagator data (see \ref PROP_DATA). This is optional.
2818 * -# Implement the interface methods (see \ref PROP_INTERFACE).
2819 * -# Implement the fundamental callback methods (see \ref PROP_FUNDAMENTALCALLBACKS).
2820 * -# Implement the additional callback methods (see \ref PROP_ADDITIONALCALLBACKS). This is optional.
2821 *
2822 * @section PROP_PROPERTIES Properties of a Propagator
2823 *
2824 * At the top of the new file "prop_mypropagator.c" you can find the propagator properties. These are given as compiler
2825 * defines. The presolving-related properties are optional,
2826 * they only have to be defined if the propagator supports presolving routines.
2827 * In the C++ wrapper class, you have to provide the propagator properties by calling the constructor of the
2828 * abstract base class scip::ObjProp from within your constructor. The properties you have the following meaning:
2829 *
2830 * @subsection PROP_FUNDAMENTALPROPERTIES Fundamental properties of a propagator
2831 *
2832 * \par PROP_NAME: the name of the propagator.
2833 * This name is used in the interactive shell to address the propagator. Additionally, if you are searching for a
2834 * propagator with SCIPfindProp(), this name is searched for. Names have to be unique: no two propagators may have the
2835 * same name.
2836 *
2837 * \par PROP_DESC: the description of the propagator.
2838 * This string is printed as a description of the propagator in the interactive shell.
2839 *
2840 * \par PROP_PRIORITY: the priority of the propagator.
2841 * In each propagation round, the propagators and propagation methods of the constraint handlers are called in a
2842 * predefined order, which is given by the priorities of the propagators and the check priorities of the constraint
2843 * handlers. First, the propagators with non-negative priority are called in order of decreasing priority. Next, the
2844 * propagation methods of the different constraint handlers are called in order of decreasing check priority. Finally,
2845 * the propagators with negative priority are called in order of decreasing priority. \n The priority of the
2846 * propagators should be set according to the complexity of the propagation algorithm and the impact of the domain
2847 * propagations: propagators providing fast algorithms that usually have a high impact (i.e., tighten many bounds)
2848 * should have a high priority.
2849 *
2850 * \par PROP_FREQ: the default frequency for propagating domains.
2851 * The frequency defines the depth levels at which the propagation method \ref PROPEXEC is called. For example, a
2852 * frequency of 7 means, that the propagation callback is executed for subproblems that are in depth 0, 7, 14, ... of
2853 * the branching tree. A frequency of 0 means that propagation is only applied in preprocessing and at the root node. A
2854 * frequency of -1 disables the propagator.
2855 * \n
2856 * The frequency can be adjusted by the user. This property of the propagator only defines the default value of the
2857 * frequency.\n
2858 * <b>Note:</b> If you want to have a more flexible control of when to execute the propagation algorithm, you have to
2859 * assign a frequency of 1 and implement a check at the beginning of your propagation algorithm whether you really want
2860 * to execute the domain propagation or not. If you do not want to execute it, set the result code to SCIP_DIDNOTRUN.
2861 *
2862 * \par PROP_DELAY: the default for whether the propagation method should be delayed, if other propagators or constraint handlers found domain reductions.
2863 * If the propagator's propagation method is marked to be delayed, it is only executed after no other propagator or
2864 * constraint handler found a domain reduction in the current iteration of the domain propagation loop. If the
2865 * propagation method of the propagator is very expensive, you may want to mark it to be delayed until all cheap
2866 * propagation methods have been executed.
2867 *
2868 * \par PROP_TIMING: the timing mask of the propagator.
2869 * SCIP calls the domain propagation routines at different places in the node processing loop.
2870 * This property indicates at which places the propagator is called.
2871 * Possible values are defined in type_timing.h and can be concatenated, e.g., as in SCIP_PROPTIMING_ALWAYS.
2872 *
2873 * @subsection PROP_ADDITIONALPROPERTIES Optional propagator properties
2874 *
2875 * The following properties are optional and only need to be defined if the propagator supports
2876 * presolving, that is, if the \ref PROPPRESOL "presolving callback" is implemented.
2877
2878 * \par PROP_PRESOLTIMING: the timing of the presolving method (FAST, MEDIUM, or EXHAUSTIVE).
2879 * Every presolving round starts with the FAST presolving methods. MEDIUM presolvers are only called, if FAST presolvers did not find
2880 * enough reductions in this round so far, and EXHAUSTIVE presolving steps are only performed if all presolvers called before
2881 * in this round were unsuccessful.
2882 * Presolving methods should be assigned a timing based on how expensive they are, e.g., presolvers that provide fast algorithms that
2883 * usually have a high impact (i.e., remove lots of variables or tighten bounds of many variables) should have a timing FAST.
2884 * If a presolving method implements different algorithms of different complexity, it may also get multiple timings and check the timing
2885 * internally in the \ref PROPPRESOL callback to decide which algorithms to run.
2886 *
2887 * \par PROP_PRESOL_PRIORITY: the priority of the presolving method.
2888 * This attribute is analogous to the PROP_PRIORITY flag, but deals with the preprocessing method of the presolver.
2889 *
2890 * \par PROP_PRESOL_MAXROUNDS: the default maximal number of presolving rounds the propagator participates in.
2891 * The preprocessing is executed in rounds.
2892 * If enough changes have been applied to the model, an additional preprocessing round is performed.
2893 * The MAXROUNDS parameter of a propagator denotes the maximal number of preprocessing rounds, the propagator
2894 * participates in.
2895 * A value of -1 means, that there is no limit on the number of rounds.
2896 * A value of 0 means, the preprocessing callback of the propagator is disabled.
2897 *
2898 * @section PROP_DATA Propagator Data
2899 *
2900 * Below the title "Data structures" you can find a struct called <code>struct SCIP_PropData</code>. In this data
2901 * structure, you can store the data of your propagator. For example, you should store the adjustable parameters of the
2902 * propagator in this data structure. If you are using C++, you can add propagator data as object variables to your
2903 * class as usual .
2904 * \n
2905 * Defining propagator data is optional. You can leave the struct empty.
2906 *
2907 *
2908 * @section PROP_INTERFACE Interface Methods
2909 *
2910 * At the bottom of "prop_mypropagator.c", you can find the interface method SCIPincludeSepaMypropagator(),
2911 * which also appears in "prop_mypropagator.h"
2912 * SCIPincludePropMypropagator() is called by the user, if (s)he wants to include the propagator,
2913 * i.e., if (s)he wants to use the propagator in his/her application.
2914 *
2915 * This method only has to be adjusted slightly.
2916 * It is responsible for notifying SCIP of the presence of the propagator. For this, you can either call SCIPincludeProp(),
2917 * or SCIPincludePropBasic() since SCIP version 3.0. In the latter variant, \ref PROP_ADDITIONALCALLBACKS "additional callbacks"
2918 * must be added via setter functions as, e.g., SCIPsetPropCopy(). We recommend this latter variant because
2919 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2920 * variant must be manually adjusted with every SCIP release containing new callbacks for separators in order to compile.
2921 *
2922 *
2923 * If you are using propagator data, you have to allocate the memory for the data at this point. You can do this by
2924 * calling
2925 * \code
2926 * SCIP_CALL( SCIPallocBlockMemory(scip, &propdata) );
2927 * \endcode
2928 * You also have to initialize the fields in <code>struct SCIP_PropData</code> afterwards.
2929 *
2930 * You may also add user parameters for your propagator, see the method SCIPincludePropPseudoobj() in
2931 * src/scip/prop_pseudoobj.c for an example.
2932 *
2933 *
2934 * @section PROP_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Propagator
2935 *
2936 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2937 * an operational algorithm.
2938 * They are passed together with the propagator itself to SCIP using SCIPincludeProp() or SCIPincludePropBasic(),
2939 * see @ref PROP_INTERFACE.
2940 *
2941 * Propagator plugins have one fundamental callback method, namely the \ref PROPEXEC method
2942 * method. This method has to be implemented for every propagator; the other callback methods are optional. In the
2943 * C++ wrapper class scip::ObjProp, the scip_exec() method (which corresponds to the \ref PROPEXEC
2944 * callback) is a virtual abstract member function. You have to
2945 * implement it in order to be able to construct an object of your propagator class.
2946 *
2947 * Additional documentation for the callback methods can be found in type_prop.h.
2948 *
2949 * @subsection PROPEXEC
2950 *
2951 * The PROPEXEC callback is called during presolving and during the subproblem processing. It should perform the actual
2952 * domain propagation, which means that it should tighten the variables' bounds. The technique of domain propagation,
2953 * which is the main workhorse of constraint programming, is called "node preprocessing" in the Integer Programming
2954 * community.
2955 *
2956 * The PROPEXEC callback has the following options:
2957 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
2958 * - reducing (i.e, tightening) the domains of some variables (result SCIP_REDUCEDDOM)
2959 * - stating that the propagator searched, but did not find domain reductions, cutting planes, or cut constraints
2960 * (result SCIP_DIDNOTFIND)
2961 * - stating that the propagator was skipped (result SCIP_DIDNOTRUN)
2962 * - stating that the propagator was skipped, but should be called again (result SCIP_DELAYED)
2963 *
2964 *
2965 *
2966 * @section PROP_ADDITIONALCALLBACKS Additional Callback Methods of a Propagator
2967 *
2968 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2969 * implemented for most applications, they can be used, for example, to initialize and free private data.
2970 * Additional callbacks can either be passed directly with SCIPincludeProp() to SCIP or via specific
2971 * <b>setter functions</b> after a call of SCIPincludePropBasic(), see also @ref PROP_INTERFACE.
2972 *
2973 * @subsection PROPRESPROP
2974 *
2975 * If the propagator wants to support \ref CONF "conflict analysis", it has to supply the PROPRESPROP method. It also should call
2976 * SCIPinferVarLbProp() or SCIPinferVarUbProp() in the domain propagation instead of SCIPchgVarLb() or SCIPchgVarUb() in
2977 * order to deduce bound changes on variables. In the SCIPinferVarLbProp() and SCIPinferVarUbProp() calls, the
2978 * propagator provides a pointer to itself and an integer value "inferinfo" that can be arbitrarily chosen.
2979 *
2980 * The propagation conflict resolving method PROPRESPROP must then be implemented to provide the "reasons" for the bound
2981 * changes, i.e., the bounds of variables at the time of the propagation, which forced the propagator to set the
2982 * conflict variable's bound to its current value. It can use the "inferinfo" tag to identify its own propagation rule
2983 * and thus identify the "reason" bounds. The bounds that form the reason of the assignment must then be provided by
2984 * calls to SCIPaddConflictLb() and SCIPaddConflictUb() in the propagation conflict resolving method.
2985 *
2986 * See the description of the propagation conflict resolving method \ref CONSRESPROP of constraint handlers for
2987 * further details.
2988 *
2989 * Omitting the PROPRESPROP callback circumvents the implementation of the usually rather complex conflict resolving method.
2990 * Yet, it
2991 * will make the conflict analysis less effective. We suggest to first omit the conflict resolving method and check how
2992 * effective the propagation method is. If it produces a lot of propagations for your application, you definitely should
2993 * consider implementing the conflict resolving method.
2994 *
2995 *
2996 * @subsection PROPFREE
2997 *
2998 * If you are using propagator data, you have to implement this method in order to free the propagator data.
2999 * This can be done by the following procedure:
3000 *
3001 * @refsnippet{src/scip/prop_redcost.c,SnippetPropFreeRedcost}
3002 *
3003 * If you have allocated memory for fields in your propagator data, remember to free this memory
3004 * before freeing the propagator data itself.
3005 * If you are using the C++ wrapper class, this method is not available.
3006 * Instead, just use the destructor of your class to free the member variables of your class.
3007 *
3008 * @subsection PROPINIT
3009 *
3010 * The PROPINIT callback is executed after the problem is transformed. The propagator may, e.g., use this call to
3011 * initialize its propagator data.
3012 *
3013 * @subsection PROPCOPY
3014 *
3015 * The PROPCOPY callback is executed when a SCIP instance is copied, e.g. to
3016 * solve a sub-SCIP. By
3017 * defining this callback as
3018 * <code>NULL</code> the user disables the execution of the specified
3019 * propagator for all copied SCIP instances. This may deteriorate the performance
3020 * of primal heuristics using sub-SCIPs.
3021 *
3022 * @subsection PROPEXIT
3023 *
3024 * The PROPEXIT callback is executed before the transformed problem is freed.
3025 * In this method, the propagator should free all resources that have been allocated for the solving process in PROPINIT.
3026 *
3027 * @subsection PROPINITPRE
3028 *
3029 * The PROPINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
3030 * The propagator may use this call to initialize its presolving data before the presolving process begins.
3031 *
3032 * @subsection PROPEXITPRE
3033 *
3034 * The PROPEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
3035 * The propagator may use this call, e.g., to clean up its presolving data.
3036 * Besides clean up, no time consuming operations should be done.
3037 *
3038 * @subsection PROPINITSOL
3039 *
3040 * The PROPINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3041 * begin.
3042 * The propagator may use this call to initialize its branch-and-bound specific data.
3043 *
3044 * @subsection PROPEXITSOL
3045 *
3046 * The PROPEXITSOL callback is executed before the branch-and-bound process is freed.
3047 * The propagator should use this call to clean up its branch-and-bound data.
3048 *
3049 * @subsection PROPPRESOL
3050 *
3051 * Seaches for domain propagations, analogous to the \ref PROPEXEC callback.
3052 * However, this callback is called during preprocessing.
3053 *
3054 * To inform SCIP that the presolving method found a reduction the result pointer has to be set in a proper way.
3055 * The following options are possible:
3056 *
3057 * - SCIP_UNBOUNDED : at least one variable is not bounded by any constraint in objective direction
3058 * - SCIP_CUTOFF : at least one domain reduction that renders the problem infeasible has been found
3059 * - SCIP_SUCCESS : the presolver found a domain reduction
3060 * - SCIP_DIDNOTFIND : the presolver searched, but did not find a presolving change
3061 * - SCIP_DIDNOTRUN : the presolver was skipped
3062 * - SCIP_DELAYED : the presolver was skipped, but should be called again
3063 *
3064 *
3065 * Please see also the @ref PROP_ADDITIONALPROPERTIES section to learn about the properties
3066 * PROP_PRESOLTIMING and PROP_PRESOL_MAXROUNDS, which influence the behaviour of SCIP
3067 * calling PROPPRESOL.
3068 *
3069 */
3070
3071/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3072
3073/**@page BRANCH How to add branching rules
3074 *
3075 * Branching rules are used to split the problem at the current node into smaller subproblems. Branching rules can be called at three
3076 * different occasions, which is why they have three different execution methods (see \ref
3077 * BRANCHRULE_ADDITIONALCALLBACKS). Branching is performed if:
3078 * - the LP solution of the current problem is fractional. In this case, the integrality constraint handler calls the
3079 * \ref BRANCHEXECLP methods of the branching rules.
3080 * - the list of external branching candidates is not empty. This will only be the case if branching candidates were added
3081 * by a user's \ref RELAX "relaxation handler" or \ref CONS "constraint handler" plugin, calling SCIPaddExternBranchCand().
3082 * These branching candidates should be processed by the \ref BRANCHEXECEXT method.
3083 * - if an integral solution violates one or more constraints and this infeasibility could not be resolved in the callback methods
3084 * \ref CONSENFOLP and \ref CONSENFOPS of the corresponding constraint handlers. In this case, the \ref BRANCHEXECPS method will be called. This is the
3085 * 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
3086 * branching on pseudo solutions works as a last resort.
3087 *
3088 * The idea of branching rules is to take a global view on the problem. In contrast, branching paradigms which are
3089 * specific to one type of constraint are best implemented within the enforcement callbacks of your constraint handler.
3090 * See, e.g., the constraint specific branching rules provided by the constraint handlers for special ordered sets
3091 * (src/scip/cons_sos{1,2}.c)).
3092 * \n
3093 * All branching rules that come with the default distribution of SCIP create two subproblems by splitting a single
3094 * variable's domain. It is, however, fully supported to implement much more general branching schemes, for example by
3095 * creating more than two subproblems, or by adding additional constraints to the subproblems instead of tightening the
3096 * domains of the variables.
3097 * \n
3098 * A complete list of all branching rules contained in this release can be found \ref BRANCHINGRULES "here".
3099 *
3100 * We now explain how users can add their own branching rules. Take the most infeasible LP branching rule
3101 * (src/scip/branch_mostinf.c) as an example. As all other default plugins, it is written in C. C++ users can easily
3102 * adapt the code by using the scip::ObjBranchrule wrapper base class and implement the scip_...() virtual methods instead of
3103 * the SCIP_DECL_BRANCH... callback methods.
3104 *
3105 * Additional documentation for the callback methods of a branching rule can be found in the file type_branch.h.
3106 *
3107 * Here is what you have to do to implement a branching rule:
3108 * -# Copy the template files src/scip/branch_xyz.c and src/scip/branch_xyz.h into files named
3109 * "branch_mybranchingrule.c" and "branch_mybranchingrule.h".
3110 * \n
3111 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
3112 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
3113 * -# Use `SCIPincludeBranchruleMybranchingrule()` in order to include the branching rule into your SCIP instance,
3114 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
3115 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
3116 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mybranchingrule".
3117 * -# Adjust the properties of the branching rule (see \ref BRANCHRULE_PROPERTIES).
3118 * -# Define the branching rule data (see \ref BRANCHRULE_DATA). This is optional.
3119 * -# Implement the interface methods (see \ref BRANCHRULE_INTERFACE).
3120 * -# Implement the fundamental callback methods (see \ref BRANCHRULE_FUNDAMENTALCALLBACKS).
3121 * -# Implement the additional callback methods (see \ref BRANCHRULE_ADDITIONALCALLBACKS). This is optional.
3122 *
3123 *
3124 * @section BRANCHRULE_PROPERTIES Properties of a Branching Rule
3125 *
3126 * At the top of the new file "branch_mybranchingrule.c" you can find the branching rule properties.
3127 * These are given as compiler defines.
3128 * In the C++ wrapper class, you have to provide the branching rule properties by calling the constructor
3129 * of the abstract base class scip::ObjBranchrule from within your constructor.
3130 * The properties you have to set have the following meaning:
3131 *
3132 * \par BRANCHRULE_NAME: the name of the branching rule.
3133 * This name is used in the interactive shell to address the branching rule.
3134 * Additionally, if you are searching for a branching rule with SCIPfindBranchrule(), this name is looked up.
3135 * Names have to be unique: no two branching rules may have the same name.
3136 *
3137 * \par BRANCHRULE_DESC: the description of the branching rule.
3138 * This string is printed as a description of the branching rule in the interactive shell.
3139 *
3140 * \par BRANCHRULE_PRIORITY: the default value for the priority of the branching rule.
3141 * In the subproblem processing, the branching rules are called in decreasing order of their priority until
3142 * one succeeded to branch. Since most branching rules are able to generate a branching in all situations,
3143 * only the rule of highest priority is used. In combination with the BRANCHRULE_MAXDEPTH and
3144 * BRANCHRULE_MAXBOUNDDIST settings, however, interesting strategies can be easily employed. For example,
3145 * the user can set the priority of the "full strong branching" strategy to the highest value and assign the
3146 * second highest value to the "reliable pseudo cost" rule. If (s)he also sets the maximal depth for the
3147 * "full strong branching" to 5, in the top 5 depth levels of the search tree the "full strong branching" is
3148 * applied, while in the deeper levels "reliable pseudo cost branching" is used.
3149 * \n
3150 * Note that the BRANCHRULE_PRIORITY property only specifies the default value of the priority. The user can
3151 * change this value arbitrarily.
3152 *
3153 * \par BRANCHRULE_MAXDEPTH: the default value for the maximal depth level of the branching rule.
3154 * This parameter denotes the maximal depth level in the branch-and-bound tree up to which the branching method of the
3155 * branching rule will be applied. Use -1 for no limit.
3156 * \n
3157 * Note that this property only specifies the default value. The user can change this value arbitrarily.
3158 *
3159 * \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.
3160 * At the current branch-and-bound node, the relative distance from its dual bound (local dual bound)
3161 * to the primal bound compared to the best node's dual bound (global dual bound) is considered. The branching method of
3162 * the branching rule will only be applied at the node if this relative distance does not exceed BRANCHRULE_MAXBOUNDDIST.
3163 * \n
3164 * For example, if the global dual bound is 50 and the primal bound is 60, BRANCHRULE_MAXBOUNDDIST = 0.25 means that
3165 * 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
3166 * 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
3167 * current best node only or at all nodes, respectively.
3168 * \n
3169 * Note that the BRANCHRULE_MAXBOUNDDIST property only specifies the default value of the maximal bound distance.
3170 * The user can change this value arbitrarily.
3171 *
3172 *
3173 * @section BRANCHRULE_DATA Branching Rule Data
3174 *
3175 * Below the header "Data structures" you can find a struct which is called "struct SCIP_BranchruleData".
3176 * In this data structure, you can store the data of your branching rule. For example, you should store the adjustable
3177 * parameters of the branching rule in this data structure.
3178 * If you are using C++, you can add branching rule data as usual as object variables to your class.
3179 * \n
3180 * Defining branching rule data is optional. You can leave the struct empty.
3181 *
3182 *
3183 * @section BRANCHRULE_INTERFACE Interface Methods
3184 *
3185 * At the bottom of "branch_mybranchingrule.c", you can find the interface method SCIPincludeBranchruleMybranchingrule(),
3186 * which also appears in "branch_mybranchingrule.h"
3187 * SCIPincludeBranchruleMybranchingrule() is called by the user, if (s)he wants to include the branching rule,
3188 * i.e., if (s)he wants to use the branching rule in his/her application.
3189 *
3190 * This method only has to be adjusted slightly.
3191 * It is responsible for notifying SCIP of the presence of the branching rule. For this, you can either call
3192 * SCIPincludeBranchrule(),
3193 * or SCIPincludeBranchruleBasic() since SCIP version 3.0. In the latter variant, \ref BRANCHRULE_ADDITIONALCALLBACKS "additional callbacks"
3194 * must be added via setter functions as, e.g., SCIPsetBranchruleCopy(). We recommend this latter variant because
3195 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3196 * variant must be manually adjusted with every SCIP release containing new callbacks for branchrule in order to compile.
3197 *
3198 *
3199 * If you are using branching rule data, you have to allocate the memory for the data at this point.
3200 * You can do this by calling:
3201 * \code
3202 * SCIP_CALL( SCIPallocBlockMemory(scip, &branchruledata) );
3203 * \endcode
3204 * You also have to initialize the fields in struct SCIP_BranchruleData afterwards.
3205 *
3206 * You may also add user parameters for your branching rule, see the method SCIPincludeBranchruleRelpscost() in
3207 * src/scip/branch_relpscost.c for an example.
3208 *
3209 *
3210 * @section BRANCHRULE_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Branching Rule
3211 *
3212 * Branching rules do not have any fundamental callback methods, i.e., all callback methods are optional.
3213 * In most cases, however, you want to implement the \ref BRANCHEXECLP method and sometimes the \ref BRANCHEXECPS method.
3214 *
3215 *
3216 * @section BRANCHRULE_ADDITIONALCALLBACKS Additional Callback Methods of a Branching Rule
3217 *
3218 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
3219 * implemented for most applications, they can be used, for example, to initialize and free private data.
3220 * Additional callbacks can either be passed directly with SCIPincludeBranchrule() to SCIP or via specific
3221 * <b>setter functions</b> after a call of SCIPincludeBranchruleBasic(), see also @ref BRANCHRULE_INTERFACE.
3222 *
3223 * The most important callback methods are the \ref BRANCHEXECLP, \ref BRANCHEXECEXT,
3224 * and \ref BRANCHEXECPS methods, which perform the actual task of generating a branching.
3225 *
3226 * Additional documentation for the callback methods can be found in type_branch.h.
3227 *
3228 * @subsection BRANCHEXECLP
3229 *
3230 * The BRANCHEXECLP callback is executed during node processing if a fractional LP solution is available. It should
3231 * split the current problem into smaller subproblems. Usually, the branching is done in a way such that the current
3232 * fractional LP solution is no longer feasible in the relaxation of the subproblems. It is, however, possible to
3233 * create a child node for which the fractional LP solution is still feasible in the relaxation, for example, by
3234 * branching on a variable with integral LP value. In every case, you have to make sure that each subproblem is a
3235 * proper restriction of the current problem. Otherwise, you risk to produce an infinite path in the search tree.
3236 *
3237 * The user gains access to the branching candidates, i.e., to the fractional variables, and their LP solution values by
3238 * calling the method SCIPgetLPBranchCands(). Furthermore, SCIP provides two methods for performing the actual
3239 * branching, namely SCIPbranchVar() and SCIPcreateChild().
3240 *
3241 * Given an integral variable \f$x\f$ with fractional LP solution value \f$x^*\f$, the method SCIPbranchVar() creates
3242 * two child nodes; one contains the bound \f$x \le \lfloor x^* \rfloor\f$ and the other one contains the bound \f$x \ge
3243 * \lceil x^* \rceil\f$, see the BRANCHEXECLP callback in src/scip/branch_mostinf.c for an example. In addition, if a
3244 * proven lower objective bound of a created child node is known, like after strong branching has been applied, the user
3245 * may call the method SCIPupdateNodeLowerbound() in order to update the child node's lower bound.
3246 *
3247 * Please also see the \ref BRANCHEXEC "further information for the three execution methods".
3248 *
3249 * @subsection BRANCHEXECEXT
3250 *
3251 * The BRANCHEXECEXT callback is executed during node processing if no LP solution is available and the list of
3252 * external branching candidates is not empty. It should split the current problem into smaller subproblems. If you
3253 * do not use relaxation handlers or constraints handlers that provide external branching candidates, you do not need to
3254 * implement this callback.
3255 *
3256 * In contrast to the LP branching candidates and the pseudo branching candidates, the list of external branching
3257 * candidates will not be generated automatically. The user has to add all variables to the list by calling
3258 * SCIPaddExternBranchCand() for each of them. Usually, this will happen in the execution method of a relaxation handler or in the
3259 * enforcement methods of a constraint handler.
3260 *
3261 * The user gains access to these branching candidates by calling the method SCIPgetExternBranchCands(). Furthermore,
3262 * SCIP provides two methods for performing the actual branching with a given solution value, namely SCIPbranchVarVal()
3263 * and SCIPcreateChild(). SCIPbranchVarVal() allows users to specify the branching point for a variable in contrast to
3264 * SCIPbranchVar(), which will always use the current LP or pseudo solution.
3265 *
3266 * This paragraph contains additional information regarding how the method SCIPbranchVarVal() works. For external branching candidates,
3267 * there are three principle possibilities:
3268 * - Given a continuous variable \f$x\f$ with solution value \f$x^*\f$, the method SCIPbranchVarVal() creates
3269 * two child nodes; one contains the bound \f$x \le x^* \f$ and the other one contains the bound \f$x \ge x^* \f$.
3270 * - Given an integer variable \f$x\f$ with fractional solution value \f$x^*\f$, the method
3271 * SCIPbranchVarVal() creates two child nodes; one contains the bound \f$x \le \lfloor x^* \rfloor\f$ and the other
3272 * one contains the bound \f$x \ge \lceil x^* \rceil\f$.
3273 * - Given an integer variable \f$x\f$ with integral solution value \f$x^*\f$, the method SCIPbranchVarVal()
3274 * creates three child nodes; one contains the bound \f$x \le x^* -1\f$, one contains the bound \f$x \ge x^* +1\f$,
3275 * one contains the fixing \f$x = x^*\f$.
3276 *
3277 * See the BRANCHEXECEXT callback in src/scip/branch_random.c for an example. In addition, if a proven lower bound of a
3278 * created child node is known the user may call the method SCIPupdateNodeLowerbound() in order to update the child
3279 * node's lower bound.
3280 *
3281 * Please also see the \ref BRANCHEXEC "further information for the three execution methods".
3282 *
3283 * @subsection BRANCHEXECPS
3284 *
3285 * The BRANCHEXECPS callback is executed during node processing if no LP solution is available and at least one of the
3286 * integer variables is not yet fixed. It should split the current problem into smaller subproblems. PS stands for
3287 * pseudo solution which is the vector of all variables set to their locally best (w.r.t. the objective function)
3288 * bounds.
3289 *
3290 * The user gains access to the branching candidates, i.e., to the non-fixed integer variables, by calling the method
3291 * SCIPgetPseudoBranchCands(). Furthermore, SCIP provides two methods for performing the actual branching, namely
3292 * SCIPbranchVar() and SCIPcreateChild().
3293 *
3294 * Given an integer variable \f$x\f$ with bounds \f$[l,u]\f$ and not having solved the LP, the method SCIPbranchVar()
3295 * creates two child nodes:
3296 * - If both bounds are finite, then the two children will contain the domain reductions \f$x \le x^*\f$, and \f$x \ge
3297 * x^*+1\f$ with \f$x^* = \lfloor \frac{l + u}{2}\rfloor\f$. The current pseudo solution will remain feasible in one
3298 * of the branches, but the hope is that halving the domain's size leads to good propagations.
3299 * - If only one of the bounds is finite, the variable will be fixed to that bound in one of the child nodes. In the
3300 * other child node, the bound will be shifted by one.
3301 * - 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$.
3302
3303 *
3304 * See the BRANCHEXECPS callback in src/scip/branch_random.c for an example. In addition, if a proven lower bound of a
3305 * created child node is known, the user may call the method SCIPupdateNodeLowerbound() in order to update the child
3306 * node's lower bound.
3307 *
3308 * Please also see the \ref BRANCHEXEC "further information for the three execution methods".
3309 *
3310 * @subsection BRANCHEXEC Further information for the three execution methods
3311 *
3312 * In order to apply more general branching schemes, one should use the method SCIPcreateChild().
3313 * After having created a child node, the additional restrictions of the child node have to be added with calls to
3314 * SCIPaddConsNode(), SCIPchgVarLbNode(), or SCIPchgVarUbNode().
3315 * \n
3316 * In the method SCIPcreateChild(), the branching rule has to assign two values to the new nodes: a node selection
3317 * priority for each node and an estimate for the objective value of the best feasible solution contained in the subtree
3318 * after applying the branching. If the method SCIPbranchVar() is used, these values are automatically assigned. For
3319 * variable based branching schemes, one might use the methods SCIPcalcNodeselPriority() and the method
3320 * SCIPcalcChildEstimate().
3321 *
3322 * In some cases, the branching rule can tighten the current subproblem instead of producing a branching. For example,
3323 * strong branching might have proven that rounding up a variable would lead to an infeasible LP relaxation and thus,
3324 * the variable must be rounded down. Therefore, the BRANCHEXECLP, BRANCHEXECPS and BRANCHEXECREL callbacks may also
3325 * produce domain reductions or add additional constraints to the current subproblem.
3326 *
3327 * The execution callbacks have the following options:
3328 * - detecting that the node is infeasible and can be cut off (result SCIP_CUTOFF)
3329 * - adding an additional constraint (e.g. a conflict constraint) (result SCIP_CONSADDED; note that this action
3330 * must not be performed if the input "allowaddcons" is FALSE)
3331 * - reducing the domain of a variable such that the current LP solution becomes infeasible (result SCIP_REDUCEDDOM)
3332 * - applying a branching (result SCIP_BRANCHED)
3333 * - stating that the branching rule was skipped (result SCIP_DIDNOTRUN).
3334 *
3335 * Only the BRANCHEXECLP callback has the possibility to add a cutting plane to the LP (result SCIP_SEPARATED).
3336 *
3337 * @subsection BRANCHFREE
3338 *
3339 * If you are using branching rule data, you have to implement this method in order to free the branching rule data.
3340 * This can be done by the following procedure:
3341 *
3342 * @refsnippet{src/scip/branch_random.c,SnippetBranchFreeRandom}
3343 *
3344 * If you have allocated memory for fields in your branching rule data, remember to free this memory
3345 * before freeing the branching rule data itself.
3346 * If you are using the C++ wrapper class, this method is not available.
3347 * Instead, just use the destructor of your class to free the member variables of your class.
3348 *
3349 * @subsection BRANCHINIT
3350 *
3351 * The BRANCHINIT callback is executed after the problem is transformed.
3352 * The branching rule may, e.g., use this call to initialize its branching rule data.
3353 *
3354 * @subsection BRANCHCOPY
3355 *
3356 * The BRANCHCOPY callback is executed when a SCIP instance is copied, e.g. to
3357 * solve a sub-SCIP. By
3358 * defining this callback as
3359 * <code>NULL</code> the user disables the execution of the specified
3360 * branching rule for all copied SCIP instances. This may deteriorate the performance
3361 * of primal heuristics using sub-SCIPs.
3362 *
3363 * @subsection BRANCHEXIT
3364 *
3365 * The BRANCHEXIT callback is executed before the transformed problem is freed.
3366 * In this method, the branching rule should free all resources that have been allocated for the solving process in
3367 * BRANCHINIT.
3368 *
3369 * @subsection BRANCHINITSOL
3370 *
3371 * The BRANCHINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3372 * begin.
3373 * The branching rule may use this call to initialize its branch-and-bound specific data.
3374 *
3375 * @subsection BRANCHEXITSOL
3376 *
3377 * The BRANCHEXITSOL callback is executed before the branch-and-bound process is freed.
3378 * The branching rule should use this call to clean up its branch-and-bound data.
3379 */
3380
3381
3382/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3383
3384/**@page CUTSEL How to add cut selectors
3385 *
3386 * Cut selectors are used to select the cuts that are going to be added to the relaxation.
3387 * For more information on how SCIP manages cuts, see "What is the difference between a sepastore and the cutpool?" in the
3388 * \ref FAQ.
3389 * \n
3390 * A complete list of all cut selectors contained in this release can be found \ref CUTSELECTORS "here".
3391 *
3392 * We now explain how users can add their own cut selectors.
3393 * Take the hybrid cut selector (src/scip/cutsel_hybrid.c) as an example.
3394 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjCutsel wrapper
3395 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_CUTSEL... callback methods.
3396 *
3397 * Additional documentation for the callback methods of a cut selector can be found in the file type_cutsel.h.
3398 *
3399 * Here is what you have to do to implement a cut selector:
3400 * -# Copy the template files src/scip/cutsel_xyz.c and src/scip/cutsel_xyz.h into files named "cutsel_mycutselector.c"
3401 * and "cutsel_mycutselector.h".
3402 * \n
3403 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
3404 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
3405 * -# Use SCIPincludeCutselMycutselector() in order to include the cut selector into your SCIP instance,
3406 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
3407 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
3408 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mycutselector".
3409 * -# Adjust the properties of the cut selector (see \ref CUTSEL_PROPERTIES).
3410 * -# Define the cut selector data (see \ref CUTSEL_DATA). This is optional.
3411 * -# Implement the interface methods (see \ref CUTSEL_INTERFACE).
3412 * -# Implement the fundamental callback methods (see \ref CUTSEL_FUNDAMENTALCALLBACKS).
3413 * -# Implement the additional callback methods (see \ref CUTSEL_ADDITIONALCALLBACKS). This is optional.
3414 *
3415 *
3416 * @section CUTSEL_PROPERTIES Properties of a Cut Selector
3417 *
3418 * At the top of the new file "cutsel_mycutselector.c" you can find the cut selector properties.
3419 * These are given as compiler defines.
3420 * In the C++ wrapper class, you have to provide the cut selector properties by calling the constructor
3421 * of the abstract base class scip::ObjCutsel from within your constructor.
3422 * The properties you have to set have the following meaning:
3423 *
3424 * \par CUTSEL_NAME: the name of the cut selector.
3425 * This name is used in the interactive shell to address the cut selector.
3426 * Additionally, if you are searching for a cut selector with SCIPfindCutsel(), this name is looked up.
3427 * Names have to be unique: no two cut selectors may have the same name.
3428 *
3429 * \par CUTSEL_DESC: the description of the cut selector.
3430 * This string is printed as a description of the cut selector in the interactive shell.
3431 *
3432 * \par CUTSEL_PRIORITY: the priority of the cut selector.
3433 * After all cuts have been collected in the sepastore, SCIP asks the cut selectors to select cuts.
3434 * The cut selectors are sorted by priority (highest goes first) and are called, in this order, until the first one
3435 * succeeds.
3436 * \n
3437 * Note that this property only defines the default value of the priority. The user may change this value arbitrarily by
3438 * adjusting the corresponding parameter setting. Whenever, even during solving, the priority of a cut selector is
3439 * changed, the cut selectors are resorted by the new priorities.
3440 *
3441 *
3442 * @section CUTSEL_DATA Cut Selector Data
3443 *
3444 * Below the header "Data structures" you can find a struct which is called "struct SCIP_CutselData".
3445 * In this data structure, you can store the data of your cut selector. For example, you should store the adjustable
3446 * parameters of the cut selector in this data structure.
3447 * If you are using C++, you can add cut selector data as usual as object variables to your class.
3448 * \n
3449 * Defining cut selector data is optional. You can leave the struct empty.
3450 *
3451 *
3452 * @section CUTSEL_INTERFACE Interface Methods
3453 *
3454 * At the bottom of "cutsel_mycutselector.c", you can find the interface method SCIPincludeCutselMycutselector(),
3455 * which also appears in "cutsel_mycutselector.h"
3456 * SCIPincludeCutselMycutselector() is called by the user, if they want to include the cut selector, i.e., if they want
3457 * to use the cut selector in their application.
3458 *
3459 * This method only has to be adjusted slightly.
3460 * It is responsible for notifying SCIP of the presence of the cut selector. For this, you can either call
3461 * SCIPincludeCutsel()
3462 * or SCIPincludeCutselBasic(). In the latter variant, \ref CUTSEL_ADDITIONALCALLBACKS "additional callbacks"
3463 * must be added via setter functions as, e.g., SCIPsetCutselCopy(). We recommend this latter variant because
3464 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3465 * variant must be manually adjusted with every SCIP release containing new callbacks for cut selectors in order to compile.
3466 *
3467 *
3468 * If you are using cut selector data, you have to allocate the memory for the data at this point.
3469 * You can do this by calling:
3470 * \code
3471 * SCIP_CALL( SCIPallocBlockMemory(scip, &cutseldata) );
3472 * \endcode
3473 * You also have to initialize the fields in struct SCIP_CutselData afterwards.
3474 *
3475 * You may also add user parameters for your cut selector, see the method SCIPincludeCutselHybrid() in
3476 * src/scip/cutsel_hybrid.c for an example.
3477 *
3478 *
3479 * @section CUTSEL_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Cut Selector
3480 *
3481 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
3482 * an operational algorithm.
3483 * They are passed together with the cut selector itself to SCIP using SCIPincludeCutsel() or SCIPincludeCutselBasic(),
3484 * see @ref CUTSEL_INTERFACE.
3485 *
3486 * Cut selector plugins have a single fundamental callback method, namely the CUTSELSELECT method.
3487 * This method has to be implemented for every cut selector; the other callback methods are optional.
3488 * It implements the single contribution every selector has to provide: Selecting cuts to be added to the relaxation.
3489 * In the C++ wrapper class scip::ObjCutsel, the scip_select() method is a virtual abstract member function.
3490 * You have to implement it in order to be able to construct an object of your cut selector class.
3491 *
3492 * @subsection CUTSELSELECT
3493 *
3494 * The CUTSELSELECT callback should decide which cuts should be added to the relaxation.
3495 * The callback receives the arrays of cuts to select from. This array must be resorted and the first nselectedcuts from
3496 * the sorted array are going to be selected.
3497 * In addition to the aforementioned cuts, the list of forced cuts is also given as an argument. This array can be used
3498 * to help with the selection algorithm. Note, however, that this array should not be tampered with.
3499 *
3500 * Additional documentation for this callback can be found in type_cutsel.h.
3501 *
3502 * @section CUTSEL_ADDITIONALCALLBACKS Additional Callback Methods of a Cut Selector
3503 *
3504 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
3505 * implemented for most applications. They can be used, for example, to initialize and free private data.
3506 * Additional callbacks can either be passed directly with SCIPincludeCutsel() to SCIP or via specific
3507 * <b>setter functions</b> after a call of SCIPincludeCutselBasic(), see also @ref CUTSEL_INTERFACE.
3508 *
3509 * @subsection CUTSELFREE
3510 *
3511 * If you are using cut selector data, you have to implement this method in order to free the cut selector data.
3512 * This can be done by the following procedure:
3513 *
3514 * @refsnippet{src/scip/cutsel_hybrid.c,SnippetCutselFreeHybrid}
3515 *
3516 * If you have allocated memory for fields in your cut selector data, remember to free this memory
3517 * before freeing the cut selector data itself.
3518 * If you are using the C++ wrapper class, this method is not available.
3519 * Instead, just use the destructor of your class to free the member variables of your class.
3520 *
3521 * @subsection CUTSELINIT
3522 *
3523 * The CUTSELINIT callback is executed after the problem is transformed.
3524 * The cut selector may, for example, use this call to initialize its cut selector data.
3525 *
3526 * @subsection CUTSELCOPY
3527 *
3528 * The CUTSELCOPY callback is executed when a SCIP instance is copied, e.g., to solve a sub-SCIP. By defining this
3529 * callback as <code>NULL</code> the user disables the execution of the specified cut selector for all copied SCIP
3530 * instances.
3531 *
3532 * @subsection CUTSELEXIT
3533 *
3534 * The CUTSELEXIT callback is executed before the transformed problem is freed.
3535 * In this method, the cut selector should free all resources that have been allocated for the solving process
3536 * in CUTSELINIT.
3537 *
3538 * @subsection CUTSELINITSOL
3539 *
3540 * The CUTSELINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3541 * begin.
3542 * The cut selector may use this call to initialize its branch-and-bound specific data.
3543 *
3544 * @subsection CUTSELEXITSOL
3545 *
3546 * The CUTSELEXITSOL callback is executed before the branch-and-bound process is freed.
3547 * The cut selector should use this call to clean up its branch-and-bound data.
3548 */
3549
3550/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3551
3552/**@page NODESEL How to add node selectors
3553 *
3554 * Node selectors are used to decide which of the leaves in the current branching tree is selected as next subproblem
3555 * to be processed. The ordering relation of the tree's leaves for storing them in the leaf priority queue is also
3556 * defined by the node selectors.
3557 * \n
3558 * A complete list of all node selectors contained in this release can be found \ref NODESELECTORS "here".
3559 *
3560 * We now explain how users can add their own node selectors.
3561 * Take the node selector for depth first search (src/scip/nodesel_dfs.c) as an example.
3562 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjNodesel wrapper
3563 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_NODESEL... callback methods.
3564 *
3565 * Additional documentation for the callback methods of a node selector can be found in the file type_nodesel.h.
3566 *
3567 * Here is what you have to do to implement a node selector:
3568 * -# Copy the template files src/scip/nodesel_xyz.c and src/scip/nodesel_xyz.h into files named "nodesel_mynodeselector.c"
3569 * and "nodesel_mynodeselector.h".
3570 * \n
3571 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
3572 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
3573 * -# Use SCIPincludeNodeselMynodeselector() in order to include the node selector into your SCIP instance,
3574 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
3575 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
3576 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mynodeselector".
3577 * -# Adjust the properties of the node selector (see \ref NODESEL_PROPERTIES).
3578 * -# Define the node selector data (see \ref NODESEL_DATA). This is optional.
3579 * -# Implement the interface methods (see \ref NODESEL_INTERFACE).
3580 * -# Implement the fundamental callback methods (see \ref NODESEL_FUNDAMENTALCALLBACKS).
3581 * -# Implement the additional callback methods (see \ref NODESEL_ADDITIONALCALLBACKS). This is optional.
3582 *
3583 *
3584 * @section NODESEL_PROPERTIES Properties of a Node Selector
3585 *
3586 * At the top of the new file "nodesel_mynodeselector.c" you can find the node selector properties.
3587 * These are given as compiler defines.
3588 * In the C++ wrapper class, you have to provide the node selector properties by calling the constructor
3589 * of the abstract base class scip::ObjNodesel from within your constructor.
3590 * The properties you have to set have the following meaning:
3591 *
3592 * \par NODESEL_NAME: the name of the node selector.
3593 * This name is used in the interactive shell to address the node selector.
3594 * Additionally, if you are searching for a node selector with SCIPfindNodesel(), this name is looked up.
3595 * Names have to be unique: no two node selectors may have the same name.
3596 *
3597 * \par NODESEL_DESC: the description of the node selector.
3598 * This string is printed as a description of the node selector in the interactive shell.
3599 *
3600 * \par NODESEL_STDPRIORITY: the default priority of the node selector in the standard mode.
3601 * The first step of each iteration of the main solving loop is the selection of the next subproblem to be processed.
3602 * The node selector of highest priority (the active node selector) is called to do this selection.
3603 * In particular, if you implemented your own node selector plugin which you want to be applied, you should choose a priority
3604 * which is greater then all priorities of the SCIP default node selectors.
3605 * Note that SCIP has two different operation modes: the standard mode and the memory saving mode. If the memory
3606 * limit - given as a parameter by the user - is almost reached, SCIP switches from the standard mode to the memory saving
3607 * mode in which different priorities for the node selectors are applied. NODESEL_STDPRIORITY is the priority of the
3608 * node selector used in the standard mode.
3609 * \n
3610 * Note that this property only defines the default value of the priority. The user may change this value arbitrarily by
3611 * adjusting the corresponding parameter setting.
3612 *
3613 * \par NODESEL_MEMSAVEPRIORITY: the default priority of the node selector in the memory saving mode.
3614 * The priority NODESEL_MEMSAVEPRIORITY of the node selector has the same meaning as the priority NODESEL_STDPRIORITY, but
3615 * is used in the memory saving mode.
3616 * Usually, you want the best performing node selector, for example best estimate search, to have maximal
3617 * standard priority, while you want a node selector which tends to keep the growth of the search tree limited, for example
3618 * depth first search, to have maximal memory saving priority.
3619 * \n
3620 * Note that this property only defines the default value of the priority. The user may change this value arbitrarily by
3621 * adjusting the corresponding parameter setting.
3622 *
3623 *
3624 * @section NODESEL_DATA Node Selector Data
3625 *
3626 * Below the header "Data structures" you can find a struct which is called "struct SCIP_NodeselData".
3627 * In this data structure, you can store the data of your node selector. For example, you should store the adjustable
3628 * parameters of the node selector in this data structure.
3629 * If you are using C++, you can add node selector data as usual as object variables to your class.
3630 * \n
3631 * Defining node selector data is optional. You can leave the struct empty.
3632 *
3633 *
3634 * @section NODESEL_INTERFACE Interface Methods
3635 *
3636 * At the bottom of "nodesel_mynodeselector.c", you can find the interface method SCIPincludeNodeselMynodeselector(),
3637 * which also appears in "nodesel_mynodeselector.h"
3638 * SCIPincludeNodeselMynodeselector() is called by the user, if (s)he wants to include the node selector,
3639 * i.e., if (s)he wants to use the node selector in his/her application.
3640 *
3641 * This method only has to be adjusted slightly.
3642 * It is responsible for notifying SCIP of the presence of the node selector. For this, you can either call
3643 * SCIPincludeNodesel(),
3644 * or SCIPincludeNodeselBasic() since SCIP version 3.0. In the latter variant, \ref NODESEL_ADDITIONALCALLBACKS "additional callbacks"
3645 * must be added via setter functions as, e.g., SCIPsetNodeselCopy(). We recommend this latter variant because
3646 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3647 * variant must be manually adjusted with every SCIP release containing new callbacks for node selectors in order to compile.
3648 *
3649 *
3650 * If you are using node selector data, you have to allocate the memory for the data at this point.
3651 * You can do this by calling:
3652 * \code
3653 * SCIP_CALL( SCIPallocBlockMemory(scip, &nodeseldata) );
3654 * \endcode
3655 * You also have to initialize the fields in struct SCIP_NodeselData afterwards.
3656 *
3657 * You may also add user parameters for your node selector, see the method SCIPincludeNodeselRestartdfs() in
3658 * src/scip/nodesel_restartdfs.c for an example.
3659 *
3660 *
3661 * @section NODESEL_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Node Selector
3662 *
3663 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
3664 * an operational algorithm.
3665 * They are passed together with the node selector itself to SCIP using SCIPincludeNodesel() or SCIPincludeNodeselBasic(),
3666 * see @ref NODESEL_INTERFACE.
3667 *
3668 * Node selector plugins have two fundamental callback methods, namely the NODESELSELECT method and the NODESELCOMP method.
3669 * These methods have to be implemented for every node selector; the other callback methods are optional.
3670 * They implement the two requirements every node selector has to fulfill: Selecting a node from the queue to be processed
3671 * next and, given two nodes, deciding which of both is favored by the node selector's selection rule. The first
3672 * task is implemented in the NODESELSELECT callback, the second one in the NODESELCOMP callback.
3673 * In the C++ wrapper class scip::ObjNodesel, the scip_select() method and the scip_comp() method (which correspond to the
3674 * NODESELSELECT callback and the NODESELCOMP callback, respectively) are virtual abstract member functions.
3675 * You have to implement them in order to be able to construct an object of your node selector class.
3676 *
3677 * Additional documentation for the callback methods can be found in type_nodesel.h.
3678 *
3679 * @subsection NODESELSELECT
3680 *
3681 * The NODESELSELECT callback is the first method called in each iteration in the main solving loop. It should decide
3682 * which of the leaves in the current branching tree is selected as the next subproblem to be processed.
3683 * It can arbitrarily decide between all leaves stored in the tree, but for performance reasons,
3684 * the current node's children and siblings are often treated different from the remaining leaves.
3685 * This is mainly due to the warm start capabilities of the simplex algorithm and the expectation that the bases of
3686 * neighboring vertices in the branching tree very similar.
3687 * The node selector's choice of the next node to process can
3688 * have a large impact on the solver's performance, because it influences the finding of feasible solutions and the
3689 * development of the global dual bound.
3690 *
3691 * Besides the ranking of the node selector, every node gets assigned a node selection priority by the branching rule
3692 * that created the node. See the \ref BRANCHEXECLP and \ref BRANCHEXECPS callbacks of the branching rules for details.
3693 * For example, the node where the branching went in the same way as the deviation from the branching variable's
3694 * root solution could be assigned a higher priority than the node where the branching went in the opposite direction.
3695 *
3696 * The following methods provide access to the various types of leaf nodes:
3697 * - SCIPgetPrioChild() returns the child of the current node with the largest node selection priority, as assigned by the
3698 * branching rule.
3699 * If no child is available (for example, because the current node was pruned), a NULL pointer is returned.
3700 * - SCIPgetBestChild() returns the best child of the current node with respect to the node selector's ordering relation as
3701 * defined by the \ref NODESELCOMP callback. If no child is available, a NULL pointer is returned.
3702 * - SCIPgetPrioSibling() returns the sibling of the current node with the largest node selection priority.
3703 * If no sibling is available (for example, because all siblings of the current node have already been processed), a NULL
3704 * pointer is returned.
3705 * Note that in binary branching every node has at most one sibling, but since SCIP supports arbitrary branching rules,
3706 * this might not always be the case.
3707 * - SCIPgetBestSibling() returns the best sibling of the current node with respect to the node selector's ordering relation
3708 * as defined by the \ref NODESELCOMP callback. If no sibling is available, a NULL pointer is returned.
3709 * - SCIPgetBestNode() returns the best leaf from the tree (children, siblings, or other leaves) with respect to the node
3710 * selector's ordering relation as defined by the \ref NODESELCOMP callback. If no open leaf exists, a NULL pointer is
3711 * returned. In this case, the optimization is finished, and the node selector should return a NULL pointer as 'selnode'.
3712 * - SCIPgetBestboundNode() returns a leaf from the tree (children, siblings, or other leaves) with the smallest lower (dual)
3713 * objective bound. If the queue is empty, a NULL pointer is returned. In this case, the optimization is finished, and the
3714 * node selector should return a NULL pointer as 'selnode'.
3715 *
3716 *
3717 * @subsection NODESELCOMP
3718 *
3719 * The NODESELCOMP callback is called to compare two leaves of the current branching tree (say node 1 and node 2)
3720 * regarding their ordering relation.
3721 *
3722 * The NODESELCOMP should return the following values:
3723 * - value < 0, if node 1 comes before (is better than) node 2
3724 * - value = 0, if both nodes are equally good
3725 * - value > 0, if node 1 comes after (is worse than) node 2.
3726 *
3727 * @section NODESEL_ADDITIONALCALLBACKS Additional Callback Methods of a Node Selector
3728 *
3729 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
3730 * implemented for most applications, they can be used, for example, to initialize and free private data.
3731 * Additional callbacks can either be passed directly with SCIPincludeNodesel() to SCIP or via specific
3732 * <b>setter functions</b> after a call of SCIPincludeNodeselBasic(), see also @ref NODESEL_INTERFACE.
3733 *
3734 * @subsection NODESELFREE
3735 *
3736 * If you are using node selector data, you have to implement this method in order to free the node selector data.
3737 * This can be done by the following procedure:
3738 *
3739 * @refsnippet{src/scip/nodesel_bfs.c,SnippetNodeselFreeBfs}
3740 *
3741 * If you have allocated memory for fields in your node selector data, remember to free this memory
3742 * before freeing the node selector data itself.
3743 * If you are using the C++ wrapper class, this method is not available.
3744 * Instead, just use the destructor of your class to free the member variables of your class.
3745 *
3746 * @subsection NODESELINIT
3747 *
3748 * The NODESELINIT callback is executed after the problem is transformed.
3749 * The node selector may, e.g., use this call to initialize its node selector data.
3750 *
3751 * @subsection NODESELCOPY
3752 *
3753 * The NODESELCOPY callback is executed when a SCIP instance is copied, e.g. to
3754 * solve a sub-SCIP. By
3755 * defining this callback as
3756 * <code>NULL</code> the user disables the execution of the specified
3757 * node selector for all copied SCIP instances. This may deteriorate the performance
3758 * of primal heuristics using sub-SCIPs.
3759 *
3760 * @subsection NODESELEXIT
3761 *
3762 * The NODESELEXIT callback is executed before the transformed problem is freed.
3763 * In this method, the node selector should free all resources that have been allocated for the solving process
3764 * in NODESELINIT.
3765 *
3766 * @subsection NODESELINITSOL
3767 *
3768 * The NODESELINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3769 * begin.
3770 * The node selector may use this call to initialize its branch-and-bound specific data.
3771 *
3772 * @subsection NODESELEXITSOL
3773 *
3774 * The NODESELEXITSOL callback is executed before the branch-and-bound process is freed.
3775 * The node selector should use this call to clean up its branch-and-bound data.
3776 */
3777
3778
3779/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3780
3781/**@page HEUR How to add primal heuristics
3782 *
3783 * Feasible solutions can be found in two different ways during the traversal of the branch-and-bound tree. On one
3784 * hand, the solution of a node's relaxation may be feasible with respect to the constraints (including the integrality).
3785 * On the other hand, feasible solutions can be discovered by primal heuristics.
3786 * \n
3787 * A complete list of all primal heuristics contained in this release can be found \ref PRIMALHEURISTICS "here".
3788 * \n
3789 * Diving heuristics are primal heuristics that explore an auxiliary search tree in a depth-first manner. Since SCIP
3790 * version 3.2, it is easy to integrate further diving heuristics by using a special controller for the scoring,
3791 * see \ref DIVINGHEUR "here" for information on how to implement a diving heuristic.
3792 * \n
3793 * We now explain how users can add their own primal heuristics.
3794 * Take the simple and fast LP rounding heuristic (src/scip/heur_simplerounding.c) as an example.
3795 * The idea of simple rounding is to iterate over all fractional variables of an LP solution and round them down,
3796 * if the variables appears only with nonnegative coefficients in the system Ax <= b and round them up if
3797 * the variables appears only with nonpositive coefficients.
3798 * If one of both conditions applies for each of the fractional variables, this will give a feasible solution.
3799 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjHeur wrapper
3800 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_HEUR... callback methods.
3801 *
3802 * Additional documentation for the callback methods of a primal heuristic can be found in the file type_heur.h.
3803 *
3804 * Here is what you have to do to implement a primal heuristic:
3805 * -# Copy the template files src/scip/heur_xyz.c and src/scip/heur_xyz.h into files named "heur_myheuristic.c"
3806 * and "heur_myheuristic.h".
3807 * \n
3808 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
3809 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
3810 * -# Use `SCIPincludeHeurMyheuristic()` in order to include the heuristic into your SCIP instance,
3811 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
3812 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
3813 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myheuristic".
3814 * -# Adjust the properties of the primal heuristic (see \ref HEUR_PROPERTIES).
3815 * -# Define the primal heuristic data (see \ref HEUR_DATA). This is optional.
3816 * -# Implement the interface methods (see \ref HEUR_INTERFACE).
3817 * -# Implement the fundamental callback methods (see \ref HEUR_FUNDAMENTALCALLBACKS).
3818 * -# Implement the additional callback methods (see \ref HEUR_ADDITIONALCALLBACKS). This is optional.
3819 *
3820 *
3821 * @section HEUR_PROPERTIES Properties of a Primal Heuristic
3822 *
3823 * At the top of the new file "heur_myheuristic.c" you can find the primal heuristic properties.
3824 * These are given as compiler defines.
3825 * In the C++ wrapper class, you have to provide the primal heuristic properties by calling the constructor
3826 * of the abstract base class scip::ObjHeur from within your constructor.
3827 * Of course, all of them are of relevant, but the most important ones for controlling the performance
3828 * are usually HEUR_FREQ and HEUR_TIMING.
3829 * The properties you have to set have the following meaning:
3830 *
3831 * \par HEUR_NAME: the name of the primal heuristic.
3832 * This name is used in the interactive shell to address the primal heuristic.
3833 * Additionally, if you are searching for a primal heuristic with SCIPfindHeur(), this name is looked up.
3834 * Names have to be unique: no two primal heuristics may have the same name.
3835 *
3836 * \par HEUR_DESC: the description of the primal heuristic.
3837 * This string is printed as a description of the primal heuristic in the interactive shell when you call "display heuristics".
3838 *
3839 * \par HEUR_DISPCHAR: the display character of the primal heuristic.
3840 * In the interactive shell, this character is printed in the first column of a status information row, if the primal
3841 * heuristic found the feasible solution belonging to the primal bound. Note that a star '*' stands for an integral
3842 * LP-relaxation.
3843 * It is recommended to select a lower or upper case letter as display character. The default primal heuristics of
3844 * SCIP use characters that describe the class to which the heuristic belongs. As an example all LP rounding heuristics
3845 * have an 'r' and all Large Neighborhood Search heuristics use the letter 'L'.
3846 * Users find commonly used display characters in type_heur.h.
3847 *
3848 *
3849 * \par HEUR_PRIORITY: the priority of the primal heuristic.
3850 * At each of the different entry points of the primal heuristics during the solving process (see HEUR_TIMING), they are
3851 * called in decreasing order of their priority.
3852 * \n
3853 * The priority of a primal heuristic should be set according to the complexity of the heuristic and the likelihood to find
3854 * feasible solutions: primal heuristics that provide fast algorithms that often succeed in finding a feasible solution should have
3855 * a high priority (like simple rounding). In addition, the interaction between different types of primal heuristics should be taken into account.
3856 * For example, improvement heuristics, which try to generate improved solutions by inspecting one or more of the feasible
3857 * solutions that have already been found, should have a low priority (like Crossover which by default needs at least 3 feasible solutions).
3858 *
3859 * \par HEUR_FREQ: the default frequency for executing the primal heuristic.
3860 * The frequency together with the frequency offset (see HEUR_FREQOFS) defines the depth levels at which the execution
3861 * method of the primal heuristic \ref HEUREXEC is called. For example, a frequency of 7 together with a frequency offset
3862 * of 5 means, that the \ref HEUREXEC callback is executed for subproblems that are in depth 5, 12, 19, ... of the branching tree. A
3863 * frequency of 0 together with a frequency offset of 3 means, that the execution method is only called at those nodes that are in
3864 * depth level 3 (i.e., at most for \f$2^3 = 8\f$ nodes if binary branching is applied).
3865 * Typical cases are: A frequency of 0 and an offset of 0 which means that
3866 * the heuristic is only called at the root node and a frequency of -1 which disables the heuristic.
3867 * \n
3868 * The frequency can be adjusted by the user. This property of the primal heuristic only defines the default value of the
3869 * frequency. If you want to have a more flexible control of when to execute the primal heuristic, you have to assign
3870 * a frequency of 1 and implement a check at the beginning of your execution method whether you really want to search for feasible
3871 * solutions or not. If you do not want to execute the method, set the result code to SCIP_DIDNOTRUN.
3872 *
3873 * \par HEUR_FREQOFS: the frequency offset for executing the primal heuristic.
3874 * The frequency offset defines the depth of the branching tree at which the primal heuristic is executed for the first
3875 * time. For example, a frequency of 7 (see HEUR_FREQ) together with a frequency offset of 10 means, that the
3876 * callback is executed for subproblems that are in depth 10, 17, 24, ... of the branching tree. In particular, assigning
3877 * different offset values to heuristics of the same type, like diving heuristics, can be useful for evenly spreading the
3878 * application of these heuristics across the branch-and-bound tree.
3879 * Note that if the frequency is equal to 1, the heuristic is applied for all nodes with depth level larger or equal to
3880 * the frequency offset.
3881 *
3882 * \par HEUR_MAXDEPTH: the maximal depth level for executing the primal heuristic.
3883 * This parameter denotes the maximal depth level in the branching tree up to which the execution method of the primal
3884 * heuristic is called. Use -1 for no limit (a usual case).
3885 *
3886 * \par HEUR_TIMING: the execution timing of the primal heuristic.
3887 * Primal heuristics have different entry points during the solving process and the execution timing parameter defines the
3888 * entry point at which the primal heuristic is executed first.
3889 * \n
3890 * The primal heuristic can be called first:
3891 * - before the processing of the node starts (SCIP_HEURTIMING_BEFORENODE)
3892 * - after each LP solve during the cut-and-price loop (SCIP_HEURTIMING_DURINGLPLOOP)
3893 * - after the cut-and-price loop was finished (SCIP_HEURTIMING_AFTERLPLOOP)
3894 * - after the processing of a node <em>with solved LP</em> was finished (SCIP_HEURTIMING_AFTERLPNODE)
3895 * - after the processing of a node <em>without solved LP</em> was finished (SCIP_HEURTIMING_AFTERPSEUDONODE)
3896 * - after the processing of the last node in the current plunge was finished, <em>and only if the LP was solved for
3897 * this node</em> (SCIP_HEURTIMING_AFTERLPPLUNGE)
3898 * - after the processing of the last node in the current plunge was finished, <em>and only if the LP was not solved
3899 * for this node</em> (SCIP_HEURTIMING_AFTERPSEUDOPLUNGE).
3900 * \par
3901 * A plunge is the successive solving of child and sibling nodes in the search tree.
3902 * The flags listed above can be combined to call the heuristic at multiple times by concatenating them with a bitwise OR.
3903 * Two useful combinations are already predefined:
3904 * - after the processing of a node was finished (SCIP_HEURTIMING_AFTERNODE; combines SCIP_HEURTIMING_AFTERLPNODE and
3905 * SCIP_HEURTIMING_AFTERPSEUDONODE)
3906 * - after the processing of the last node in the current plunge was finished (SCIP_HEURTIMING_AFTERPLUNGE; combines
3907 * SCIP_HEURTIMING_AFTERLPPLUNGE and SCIP_HEURTIMING_AFTERPSEUDOPLUNGE)
3908 * \par
3909 * Calling a primal heuristic "before the processing of the node starts" is particularly useful for heuristics
3910 * that do not need to access the LP solution of the current node. If such a heuristic finds a feasible solution, the
3911 * leaves of the branching tree exceeding the new primal bound are pruned. It may happen that even the current node can
3912 * be cut off without solving the LP relaxation. Combinatorial heuristics, like the farthest insert heuristic for the TSP
3913 * (see examples/TSP/src/HeurFarthestInsert.cpp), are often applicable at this point.
3914 * \n
3915 * Very fast primal heuristics that require an LP solution can also be called "after each LP solve during the
3916 * cut-and-price loop". Rounding heuristics, like the simple and fast LP rounding heuristic
3917 * (src/scip/heur_simplerounding.c), belong to this group of primal heuristics.
3918 * \n
3919 * Most heuristics, however, are called either after a node was completely processed
3920 * (e.g. expensive rounding heuristics like RENS), or even only after a full plunge was finished (e.g., diving heuristics).
3921 *
3922 * \par HEUR_USESSUBSCIP: Does the heuristic use a secondary SCIP instance?
3923 * Some heuristics and separators solve MIPs or SAT problems using a secondary SCIP instance. Examples are
3924 * Large Neighborhood Search heuristics such as RINS and Local Branching or the CGMIP separator. To avoid recursion,
3925 * these plugins usually deactivate all other plugins that solve MIPs. If a heuristic uses a secondary SCIP instance,
3926 * this parameter has to be TRUE and it is recommended to call SCIPsetSubscipsOff() for the secondary SCIP instance.
3927 *
3928 * Computational experiments indicate that for the overall performance of a MIP solver, it is important to evenly
3929 * spread the application of the heuristics across the branch-and-bound tree. Thus, the assignment of the parameters
3930 * HEUR_FREQ, HEUR_FREQOFS, and HEUR_TIMING should contribute to this aim.
3931 *
3932 * Note that all diving heuristics in the SCIP distribution (see, e.g., src/scip/heur_guideddiving.c) check whether other diving
3933 * heuristics have already been called at the current node. This can be done by comparing SCIPgetLastDivenode(scip) and
3934 * SCIPgetNNodes(scip). If the two are equal, and if the current node is not the root node (SCIPgetDepth(scip) > 0), diving
3935 * heuristics should be delayed by returning the result code 'SCIP_DELAYED'. This is an additional contribution to the goal of
3936 * not calling multiple similar heuristics at the same node.
3937 *
3938 *
3939 * @section HEUR_DATA Primal Heuristic Data
3940 *
3941 * Below the header "Data structures" you can find a struct which is called "struct SCIP_HeurData".
3942 * In this data structure, you can store the data of your primal heuristic. For example, you should store the adjustable
3943 * parameters of the primal heuristic or a working solution in this data structure.
3944 * If you are using C++, you can add primal heuristic data as usual as object variables to your class.
3945 * \n
3946 * Defining primal heuristic data is optional. You can leave the struct empty.
3947 *
3948 *
3949 * @section HEUR_INTERFACE Interface Methods
3950 *
3951 * At the bottom of "heur_myheuristic.c", you can find the interface method SCIPincludeHeurMyheuristic(),
3952 * which also appears in "heur_myheuristic.h"
3953 * SCIPincludeHeurMyheuristic() is called by the user, if (s)he wants to include the heuristic,
3954 * i.e., if (s)he wants to use the heuristic in his/her application.
3955 *
3956 * This method only has to be adjusted slightly.
3957 * It is responsible for notifying SCIP of the presence of the heuristic. For this, you can either call
3958 * SCIPincludeHeur(),
3959 * or SCIPincludeHeurBasic() since SCIP version 3.0. In the latter variant, \ref HEUR_ADDITIONALCALLBACKS "additional callbacks"
3960 * must be added via setter functions as, e.g., SCIPsetHeurCopy(). We recommend this latter variant because
3961 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3962 * variant must be manually adjusted with every SCIP release containing new callbacks for heuristics in order to compile.
3963 *
3964 * If you are using primal heuristic data, you have to allocate the memory for the data at this point.
3965 * You can do this by calling:
3966 * \code
3967 * SCIP_CALL( SCIPallocBlockMemory(scip, &heurdata) );
3968 * \endcode
3969 * You also have to initialize the fields in struct SCIP_HeurData afterwards.
3970 *
3971 * You may also add user parameters for your primal heuristic, see the method SCIPincludeHeurFeaspump() in
3972 * src/scip/heur_oneopt.c for an example where a single Boolean parameter is added.
3973 *
3974 *
3975 * @section HEUR_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Primal Heuristic
3976 *
3977 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
3978 * an operational algorithm.
3979 * They are passed together with the primal heuristic itself to SCIP using SCIPincludeHeur() or SCIPincludeHeurBasic(),
3980 * see @ref HEUR_INTERFACE.
3981 *
3982 *
3983 * Primal heuristic plugins have only one fundamental callback method, namely the HEUREXEC method.
3984 * This method has to be implemented for every primal heuristic; the other callback methods are optional.
3985 * In the C++ wrapper class scip::ObjHeur, the scip_exec() method (which corresponds to the HEUREXEC callback) is a virtual
3986 * abstract member function. You have to implement it in order to be able to construct an object of your primal heuristic
3987 * class.
3988 *
3989 * Additional documentation for the callback methods can be found in type_heur.h.
3990 *
3991 * @subsection HEUREXEC
3992 *
3993 * The HEUREXEC callback is called at different positions during the node processing loop, see HEUR_TIMING. It should
3994 * search for feasible solutions and add them to the solution pool. For creating a new feasible solution, the
3995 * methods SCIPcreateSol() and SCIPsetSolVal() can be used. Afterwards, the solution can be added to the storage by
3996 * calling the method SCIPtrySolFree() (or SCIPtrySol() and SCIPfreeSol()).
3997 *
3998 * The HEUREXEC callback gets a SCIP pointer, a pointer to the heuristic itself, the current point in the
3999 * solve loop and a result pointer as input (see type_heur.h).
4000 *
4001 * The heuristic has to set the result pointer appropriately!
4002 * Therefore it has the following options:
4003 * - finding at least one feasible solution (result SCIP_FOUNDSOL)
4004 * - stating that the primal heuristic searched, but did not find a feasible solution (result SCIP_DIDNOTFIND)
4005 * - stating that the primal heuristic was skipped (result SCIP_DIDNOTRUN)
4006 * - stating that the primal heuristic was skipped, but should be called again (result SCIP_DELAYED).
4007 *
4008 *
4009 * @section HEUR_ADDITIONALCALLBACKS Additional Callback Methods of a Primal Heuristic
4010 *
4011 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
4012 * implemented for most applications, they can be used, for example, to initialize and free private data.
4013 * Additional callbacks can either be passed directly with SCIPincludeHeur() to SCIP or via specific
4014 * <b>setter functions</b> after a call of SCIPincludeHeurBasic(), see also @ref HEUR_INTERFACE.
4015 *
4016 * @subsection HEURFREE
4017 *
4018 * If you are using primal heuristic data, you have to implement this method in order to free the primal heuristic data.
4019 * This can be done by the following procedure:
4020 *
4021 * @refsnippet{applications/Coloring/src/heur_init.c,SnippetHeurFreeInit}
4022 *
4023 * If you have allocated memory for fields in your primal heuristic data, remember to free this memory
4024 * before freeing the primal heuristic data itself.
4025 * If you are using the C++ wrapper class, this method is not available.
4026 * Instead, just use the destructor of your class to free the member variables of your class.
4027 *
4028 * @subsection HEURINIT
4029 *
4030 * The HEURINIT callback is executed after the problem is transformed.
4031 * The primal heuristic may, e.g., use this call to initialize its primal heuristic data.
4032 *
4033 * @subsection HEURCOPY
4034 *
4035 * The HEURCOPY callback is executed when a SCIP instance is copied, e.g. to
4036 * solve a sub-SCIP. By
4037 * defining this callback as
4038 * <code>NULL</code> the user disables the execution of the specified
4039 * heuristic for all copied SCIP instances. This may deteriorate the performance
4040 * of primal heuristics using sub-SCIPs.
4041 *
4042 * @subsection HEUREXIT
4043 *
4044 * The HEUREXIT callback is executed before the tDIVINGHEURransformed problem is freed.
4045 * In this method, the primal heuristic should free all resources that have been allocated for the solving process in
4046 * HEURINIT.
4047 *
4048 * @subsection HEURINITSOL
4049 *
4050 * The HEURINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
4051 * begin. The primal heuristic may use this call to initialize its branch-and-bound specific data.
4052 *
4053 * @subsection HEUREXITSOL
4054 *
4055 * The HEUREXITSOL callback is executed before the branch-and-bound process is freed. The primal heuristic should use this
4056 * call to clean up its branch-and-bound data, which was allocated in HEURINITSOL.
4057 */
4058
4059/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4060
4061/**@page EXPRHDLR How to add expression handlers
4062 *
4063 * Expression handlers define basic expression types and provide additional functionality to work with expressions,
4064 * e.g., differentiation, simplification, estimation, hashing, copying, printing, parsing.
4065 * A complete list of all expression handlers contained in this release can be found \ref EXPRHDLRS "here".
4066 * In addition to expression handlers, higher level nonlinear structures are handled by nonlinear handlers, see \ref NLHDLR.
4067 *
4068 * Here is what you have to do to implement an own expression handler:
4069 * -# 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
4070 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
4071 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
4072 * -# Use `SCIPincludeExprhdlrMyfunc()` in order to include the expression handler into your SCIP instance,
4073 * e.g., in the main file of your project. \n
4074 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
4075 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myfunc".
4076 * -# Adjust the properties of the expression handler (see \ref EXPRHDLR_PROPERTIES).
4077 * -# Define the expression handler data and expression data (see \ref EXPRHDLR_DATA). This is optional.
4078 * -# Implement the interface methods (see \ref EXPRHDLR_INTERFACE).
4079 * -# Implement the fundamental callback methods (see \ref EXPRHDLR_FUNDAMENTALCALLBACKS).
4080 * -# Implement the additional callback methods (see \ref EXPRHDLR_ADDITIONALCALLBACKS), where necessary.
4081 *
4082 * Additional documentation for the callback methods of an expression handler, in particular for the input parameters,
4083 * can be found in the file \ref type_expr.h.
4084 *
4085 * For a complete implementation of an expression handler, take the one for exponential expressions (src/scip/expr_exp.c) as an example.
4086 *
4087 * @section EXPRHDLR_PROPERTIES Properties of an Expression Handler
4088 *
4089 * At the top of the new file `expr_myfunc.c`, you can find the expression handler properties.
4090 * These are given as compiler defines.
4091 * The properties you have to set have the following meaning:
4092 *
4093 * \par EXPRHDLR_NAME: the name of the expression handler.
4094 * This name is used in the interactive shell to address the expression handler.
4095 * Additionally, if you or a parsing routine is searching for an expression handler with SCIPfindExprhdlr(), this name is looked up.
4096 * Names have to be unique: no two expression handlers may have the same name.
4097 *
4098 * \par EXPRHDLR_DESC: the description of the expression handler.
4099 * This string is printed as a description of the expression handler in the interactive shell.
4100 *
4101 * \par EXPRHDLR_PRECEDENCE: the precedence of the expression handler.
4102 * Precedence of the expression operation relative to other expressions when printing the expression.
4103 *
4104 * @section EXPRHDLR_DATA Expression Handler Data and Expression Data
4105 *
4106 * Below the header "Data structures" you can find structs called `struct SCIP_ExprhdlrData` and `struct SCIP_ExprData`.
4107 * In this first data structure, you can store the data of your expression handler.
4108 * For example, you should store the adjustable parameters of the expression handler in this data structure.
4109 * In the second data structure, you can store data that is unique to an expression.
4110 * For example, the pow expression handler stores the exponent in this data structure.
4111 * \n
4112 * Defining expression handler data and expression data is optional. You can leave these structs empty.
4113 *
4114 * @section EXPRHDLR_INTERFACE Interface Methods
4115 *
4116 * @subsection EXPRHDLR_INCLUDE SCIPincludeExprhdlrMyfunc()
4117 *
4118 * At the bottom of `expr_myfunc.c`, you can find the interface method `SCIPincludeExprhdlrMyfunc()`,
4119 * which also appears in `expr_myfunc.h`.
4120 * `SCIPincludeExprhdlrMyfunc()` is called by the user, if (s)he wants to include the expression handler,
4121 * i.e., if (s)he wants to use the expression handler in his/her application.
4122 *
4123 * This method is responsible for notifying SCIP of the presence of the expression handler.
4124 * For this, you must call SCIPincludeExprhdlr() from SCIPincludeExprhdlrMyfunc().
4125 * The function only expects the properties and fundamental callbacks of the expression handler as arguments.
4126 * \ref EXPRHDLR_ADDITIONALCALLBACKS "Additional callbacks" must be added via setter functions as, e.g., SCIPexprhdlrSetCopyFreeHdlr().
4127 *
4128 * If you are using expression handler data, you have to allocate the memory for the data at this point.
4129 * You can do this by calling:
4130 * \code
4131 * SCIP_CALL( SCIPallocBlockMemory(scip, &exprhdlrdata) );
4132 * \endcode
4133 * You also have to initialize the fields in `struct SCIP_ExprhdlrData` afterwards.
4134 * For freeing the expression handler data, see \ref EXPRFREEHDLR.
4135 *
4136 * You may also add user parameters for your expression handler, see \ref PARAM for how to add user parameters.
4137 *
4138 * For the logarithm expression handler, the include method is as follows:
4139 * @refsnippet{src/scip/expr_log.c,SnippetIncludeExprhdlrLog}
4140 *
4141 * @subsection EXPRHDLR_CREATEEXPR SCIPcreateExprMyfunc()
4142 *
4143 * Another interface method that can be found in `expr_myfunc.c` is `SCIPcreateExprMyfunc()`.
4144 * This method is called by the user, if (s)he wants to create an expression that is handled by this expression handler.
4145 * Typically, the creation function takes the operands of the expression (the children) as arguments.
4146 * `SCIPcreateExprMyfunc()` may further be extended to take parameters of an expression into account.
4147 * For example, SCIPcreateExprPow() receives the exponent as argument.
4148 *
4149 * In the implementation of `SCIPcreateExprMyfunc()`, the expression data shall be allocated and initialized, if the expression has data
4150 * (like the exponent of pow expressions).
4151 * Then the expression shall be created by a call to SCIPcreateExpr().
4152 * This function takes the expression handler, expression data, children, and ownercreate callback as arguments.
4153 * For freeing the expression data, see \ref EXPRFREEDATA.
4154 *
4155 * The `ownercreate` and `ownercreatedata` that are passed to `SCIPcreateExprMyfunc()` need to be passed on to SCIP.
4156 * The owner of the expression that is created uses these arguments to store additional data in an expression.
4157 * For most usecases, these arguments will be set to `NULL`.
4158 * However, if the \ref EXPRPARSE callback is implemented, then `SCIPcreateExprMyfunc()` may need to be called with a non-NULL value
4159 * for `ownercreate` and `ownercreatedata`.
4160 * This will be the case if, for example, the constraint handler for nonlinear constraint parses an expression.
4161 * The constraint handler will then own the expression and needs to store some data in the expression.
4162 *
4163 * For the product expression handler, the expression create function is as follows:
4164 * @refsnippet{src/scip/expr_product.c,SnippetCreateExprProduct}
4165 *
4166 *
4167 * @section EXPRHDLR_FUNDAMENTALCALLBACKS Fundamental Callback Methods of an Expression Handler
4168 *
4169 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
4170 * an operational algorithm.
4171 * They are passed to SCIP when the expression handler is created and included in SCIP via SCIPincludeExprhdlr(),
4172 * see @ref EXPRHDLR_INTERFACE.
4173 *
4174 * Expression handlers have one fundamental callback, @ref EXPREVAL, that needs to be implemented.
4175 * However, expression handlers with stateful expressions (expressions that have data) need to implement also the
4176 * @ref EXPRCOPYDATA, @ref EXPRFREEDATA, and @ref EXPRCOMPARE callbacks.
4177 *
4178 * Additional documentation for the callback methods, in particular relating to their input parameters,
4179 * can be found in \ref type_expr.h.
4180 *
4181 * @subsection EXPREVAL
4182 *
4183 * The expression evaluation callback defines the mathematical operation that the expression handler represents.
4184 * Its purpose is to evaluate an expression by taking the values of its children (operands) into account.
4185 *
4186 * The children of the expression can be retrieved via SCIPexprGetChildren() and SCIPexprGetNChildren().
4187 * The value (a `SCIP_Real`) for each child can be retrieved via function SCIPexprGetEvalValue().
4188 * The value of the expression should be stored in the argument `val` that is passed to the callback.
4189 * For example, the evaluation in the expression handler for sum is doing the following:
4190 * @refsnippet{src/scip/expr_sum.c,SnippetExprEvalSum}
4191 *
4192 * When an expression cannot be evaluated w.r.t. the values of its children, such a domain error must be signaled
4193 * to SCIP by setting `*val` to `SCIP_INVALID`.
4194 * SCIP then aborts evaluation. It is thus not necessary to check in the evaluation callback whether any child
4195 * has value `SCIP_INVALID`.
4196 * For example, the evaluation in the expression handler for logarithm expressions is doing the following:
4197 * @refsnippet{src/scip/expr_log.c,SnippetExprEvalLog}
4198 *
4199 * The solution (`sol`) that is passed to EXPREVAL can usually be ignored.
4200 * It is used by the expression handler for variables to retrieve the value of a variable expression.
4201 *
4202 *
4203 * @section EXPRHDLR_ADDITIONALCALLBACKS Additional Callback Methods of an Expression Handler
4204 *
4205 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
4206 * implemented for most applications; they can be used, for example, to initialize and free private data.
4207 * Additional callbacks can be passed via specific
4208 * <b>setter functions</b> after a call of SCIPincludeExprhdlr(), see also @ref EXPRHDLR_INCLUDE.
4209 *
4210 * @subsection EXPRCOPYHDLR
4211 *
4212 * This method should include the expression handler into a given SCIP instance.
4213 * It is usually called when a copy of SCIP is generated.
4214 *
4215 * By not implementing this callback, the expression handler will not be available in copied SCIP instances.
4216 * If a nonlinear constraint uses expressions of this type, it will not be possible to copy them.
4217 * This may deteriorate the performance of primal heuristics using sub-SCIPs.
4218 *
4219 * @subsection EXPRFREEHDLR
4220 *
4221 * If you are using expression handler data (see \ref EXPRHDLR_DATA and \ref EXPRHDLR_INCLUDE), you have to implement this method
4222 * in order to free the expression handler data.
4223 *
4224 * @subsection EXPRCOPYDATA
4225 *
4226 * This method is called when creating copies of an expression within
4227 * the same or between different SCIP instances. It is given the
4228 * source expression, whose data shall be copied, and expects that
4229 * the data for the target expression is returned. This data will then be used
4230 * to create a new expression.
4231 *
4232 * If expressions that are handled by this expression handler have no data,
4233 * then this callback can be omitted.
4234 *
4235 * @subsection EXPRFREEDATA
4236 *
4237 * This method is called when freeing an expression that has data.
4238 * It is given an expression and shall free its expression data.
4239 * It shall then call `SCIPexprSetData(expr, NULL)`.
4240 *
4241 * This callback must be implemented for expressions that have data.
4242 *
4243 * @subsection EXPRPRINT
4244 *
4245 * This callback is called when an expression is printed.
4246 * It is called while DFS-iterating over the expression at different stages, that is,
4247 * when the expression is visited the first time, before each child of the expression is visited,
4248 * after each child of the expression has been visited, and when the iterator leaves the expression
4249 * for its parent.
4250 * At the various stages, the expression may print a string.
4251 * The given precedence of the parent expression can be used to decide whether parenthesis need to be printed.
4252 *
4253 * 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:
4254 * @refsnippet{src/scip/expr_pow.c,SnippetExprPrintPow}
4255 *
4256 * The pow expression handler does not yet take expression precedence into account to decide whether the parenthesis around `f(x)` can be omitted.
4257 * For the sum expression handler, this has been implemented:
4258 * @refsnippet{src/scip/expr_sum.c,SnippetExprPrintSum}
4259 *
4260 * If this callback is not implemented, the expression is printed as `<hdlrname>(<child1>, <child2>, ...)`.
4261 *
4262 * @subsection EXPRPARSE
4263 *
4264 * This callback is called when an expression is parsed from a string and an operator with the name of the expression handler is found.
4265 * The given string points to the beginning of the arguments of the expression, that is, the beginning of "..." in the string `myfunc(...)`.
4266 * The callback shall interpret "..." and create an expression, probably via `SCIPcreateExprMyfunc()`, and return this created expression
4267 * and the position of the last character in "..." to SCIP.
4268 * When creating an expression, the given `ownercreate` and `ownercreatedata` shall be passed on.
4269 *
4270 * The string "..." likely contains one or several other expressions that will be the children of the `myfunc` expression.
4271 * `SCIPparseExpr()` shall be used to parse these expressions.
4272 *
4273 * For an expression that takes only one argument and has no parameters, the parsing routine is straightforward.
4274 * For example:
4275 * @refsnippet{src/scip/expr_exp.c,SnippetExprParseExp}
4276 *
4277 * For an expression that has additional data, the parsing routine is slightly more complex.
4278 * For the signpower expression, this parses `signpower(<child>,<exponent>)`:
4279 * @refsnippet{src/scip/expr_pow.c,SnippetExprParseSignpower}
4280 *
4281 * If this callback is not implemented, the expression cannot be parsed.
4282 * For instance, `.cip` files with nonlinear constraints that use this expression cannot be read.
4283 *
4284 * @subsection EXPRCURVATURE
4285 *
4286 * This callback is called when an expression is checked for convexity or concavity.
4287 * It is important to note that the callback is given a desired curvature (convex, concave, or both (=linear))
4288 * and the callback is required to return whether the given expression has the desired curvature.
4289 * In addition, it can state conditions on the curvature of the children under which the desired curvature
4290 * can be achieved and it can take bounds on the children into account.
4291 * SCIPevalExprActivity() and SCIPexprGetActivity() shall be used to evaluate and get bounds on a child expression.
4292 *
4293 * The implementation in the absolute-value expression handler serves as an example:
4294 * @refsnippet{src/scip/expr_abs.c,SnippetExprCurvatureAbs}
4295 *
4296 * If this callback is not implemented, the expression is assumed to be indefinite.
4297 *
4298 * @subsection EXPRMONOTONICITY
4299 *
4300 * This callback is called when an expression is checked for its monotonicity with respect to a given child.
4301 * It is given the index of the child and shall return whether the expression is monotonically increasing or decreasing with respect to this child,
4302 * that is, when assuming that all other children are fixed.
4303 * Bounds on the children can be taken into account.
4304 * These can be evaluated and obtained via SCIPevalExprActivity() and SCIPexprGetActivity().
4305 *
4306 * The implementation in the absolute value expression handler serves as an example:
4307 * @refsnippet{src/scip/expr_abs.c,SnippetExprMonotonicityAbs}
4308 *
4309 * If this callback is not implemented, the expression is assumed to be not monotone in any child.
4310 *
4311 * @subsection EXPRINTEGRALITY
4312 *
4313 * This callback is called when an expression is checked for integrality, that is,
4314 * whether the expression evaluates always to an integral value in a feasible solution.
4315 * An implementation usually uses SCIPexprIsIntegral() to check whether children evaluate to an integral value.
4316 *
4317 * For example, a sum expression is returned to be integral if all coefficients and all children are integral:
4318 * @refsnippet{src/scip/expr_sum.c,SnippetExprIntegralitySum}
4319 *
4320 * If this callback is not implemented, the expression is assumed to be not integral.
4321 *
4322 * @subsection EXPRHASH
4323 *
4324 * This callback is called when a hash value is computed for an expression.
4325 * The hash is used to quickly identify expressions that may be equal (or better: to identify expressions that cannot be pairwise equal).
4326 *
4327 * The hash shall be unique to the expression as likely as positive.
4328 * To achieve this, the hashing algorithm shall use the expression type, expression data, and hash of children as input.
4329 * It must also be deterministic in this input.
4330 *
4331 * For example, for the sum expression, the coefficients and the hashes of all children are taken into account:
4332 * @refsnippet{src/scip/expr_sum.c,SnippetExprHashSum}
4333 *
4334 * `EXPRHDLR_HASHKEY` is a constant that is unique to the sum expression handler.
4335 *
4336 * If this callback is not implemented, a hash is computed from the expression handler name and the hashes of all children.
4337 *
4338 * @subsection EXPRCOMPARE
4339 *
4340 * This callback is called when two expressions (expr1 and expr2) that are handled by the expression handlers need to be compared.
4341 * The method shall impose an order on expressions and thus must return
4342 * - -1 if expr1 < expr2, or
4343 * - 0 if expr1 = expr2, or
4344 * - 1 if expr1 > expr2.
4345 *
4346 * The callback may use SCIPcompareExpr() to compare children of expr1 and expr2.
4347 *
4348 * For example, for pow expressions, the order is given by the order of the children.
4349 * If the children are equal, then the order of the exponents is used:
4350 * @refsnippet{src/scip/expr_pow.c,SnippetExprComparePow}
4351 *
4352 * If this callback is not implemented, a comparison is done based on the children of expr1 and expr2 only.
4353 * If the expression is stateful, it must implement this callback.
4354 *
4355 * @subsection EXPRBWDIFF
4356 *
4357 * This callback is called when the gradient or Hessian of a function that is represented by an expression is computed.
4358 *
4359 * The method shall compute the partial derivative of the expression w.r.t. a child with specified childidx.
4360 * That is, it should return
4361 * \f[
4362 * \frac{\partial \text{expr}}{\partial \text{child}_{\text{childidx}}}
4363 * \f]
4364 *
4365 * See also \ref SCIP_EXPR_DIFF "Differentiation methods in scip_expr.h" for more details on automatic differentiation of expressions.
4366 *
4367 * For the product expression, backward differentiation is implemented as follows:
4368 * @refsnippet{src/scip/expr_product.c,SnippetExprBwdiffProduct}
4369 *
4370 * If this callback is not implemented, gradients and Hessian of functions that involve this expression cannot be computed.
4371 * This can be hurtful for performance because linear relaxation routines that rely on gradient evaluation (e.g., nlhdlr_convex) cannot be used.
4372 *
4373 * @subsection EXPRFWDIFF
4374 *
4375 * This callback is called when the Hessian of a function that is represented by an expression is computed.
4376 * It may also be used to compute first derivatives.
4377 *
4378 * The method shall evaluate the directional derivative of the expression when interpreted as an operator
4379 * \f$ f(c_1, \ldots, c_n) \f$, where \f$ c_1, \ldots, c_n \f$ are the children.
4380 * The directional derivative is
4381 * \f[
4382 * \sum_{i = 1}^n \frac{\partial f}{\partial c_i} D_u c_i,
4383 * \f]
4384 * 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,
4385 * which can be accessed via SCIPexprGetDot().
4386 * The point at which to compute the derivative is given by SCIPexprGetEvalValue().
4387 *
4388 * See also \ref SCIP_EXPR_DIFF "Differentiation methods in scip_expr.h" for more details on automatic differentiation of expressions.
4389 *
4390 * 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$:
4391 * @refsnippet{src/scip/expr_product.c,SnippetExprFwdiffProduct}
4392 *
4393 * 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.
4394 *
4395 * @subsection EXPRBWFWDIFF
4396 *
4397 * This callback is called when the Hessian of a function that is represented by an expression is computed.
4398 *
4399 * The method computes the total derivative, w.r.t. its children, of the partial derivative of expr w.r.t. childidx.
4400 * Equivalently, it computes the partial derivative w.r.t. childidx of the total derivative.
4401 *
4402 * 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,
4403 * and the method should return
4404 * \f[
4405 * \sum_{i = 1}^n \frac{\partial^2 f}{\partial c_i} \partial c_{\text{childidx}} D_u c_i,
4406 * \f]
4407 * 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,
4408 * which can be accessed via SCIPexprGetDot().
4409 *
4410 * Thus, if \f$ n = 1 \f$ (i.e., the expression represents a univariate operator), the method should return
4411 * \f[
4412 * f^{\prime \prime}(\text{SCIPexprGetEvalValue}(c)) D_u c.
4413 * \f]
4414 *
4415 * See also \ref SCIP_EXPR_DIFF "Differentiation methods in scip_expr.h" for more details on automatic differentiation of expressions.
4416 *
4417 * For a product, \f$f(x) = c\prod_i x_i\f$, the directional derivative is
4418 * \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$:
4419 * @refsnippet{src/scip/expr_product.c,SnippetExprBwfwdiffProduct}
4420 *
4421 * If this callback is not implemented, there is currently no particular performance impact.
4422 * 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.
4423 *
4424 * @subsection EXPRINTEVAL
4425 *
4426 * This callback is called when bounds on an expression need to be computed.
4427 * 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.
4428 * The latter can be accessed via SCIPexprGetActivity().
4429 *
4430 * Often, interval evaluation is implemented analogous to evaluation with numbers.
4431 * For example, for products:
4432 * @refsnippet{src/scip/expr_product.c,SnippetExprIntevalProduct}
4433 *
4434 * 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.
4435 *
4436 * @subsection EXPRESTIMATE
4437 *
4438 * While \ref EXPRINTEVAL computes constant under- and overestimators,
4439 * this callback is called when linear under- or overestimators need to be computed.
4440 * The estimator shall be as tight as possible at a given point and must be valid w.r.t. given (local) bounds.
4441 * If the value of the estimator in the reference point is smaller (larger) than a given targetvalue
4442 * when underestimating (overestimating), then no estimator needs to be computed.
4443 * Note, that targetvalue can be infinite if any estimator will be accepted.
4444 *
4445 * The callback shall also indicate whether the estimator is also valid w.r.t. given global bounds and for which
4446 * child a reduction in the local bounds (usually by branching) would improve the estimator.
4447 *
4448 * For the absolute-value expression, the under- and overestimators are computed as follows:
4449 * @refsnippet{src/scip/expr_abs.c,SnippetExprEstimateAbs}
4450 *
4451 * 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.
4452 *
4453 * @subsection EXPRINITESTIMATES
4454 *
4455 * This callback is similar to \ref EXPRESTIMATE, but is not given a reference point.
4456 * It can also return several (up to \ref SCIP_EXPR_MAXINITESTIMATES many) estimators.
4457 * A usecase for this callback is the construction of an initial linear relaxation of nonlinear constraints.
4458 *
4459 * For the absolute-value expression, the following initial under- and overestimators are computed:
4460 * @refsnippet{src/scip/expr_abs.c,SnippetExprInitestimatesAbs}
4461 *
4462 * If this callback is not implemented, the initial linear relaxation for nonlinear constraints may be less tight.
4463 * This can have a minor effect on performance, as long as \ref EXPRESTIMATE has been implemented and the linear relaxation
4464 * is still bounded (e.g., when all nonlinear variables have finite bounds).
4465 *
4466 * @subsection EXPRSIMPLIFY
4467 *
4468 * This callback shall try to simplify an expression by applying algebraic transformations.
4469 * It shall return the simplified (and equivalent) expression.
4470 * It can assume that children have been simplified.
4471 * If no simplification is possible, then it can return the original expression, but needs to capture it.
4472 * When creating a new expression, it shall pass on the given ownerdata creation callback and its data.
4473 *
4474 * A simplification that should be implemented by every expression handler at the moment is constant-folding, i.e.,
4475 * returning a value-expression if every child is a value expression.
4476 * For an example, the simplification for the exponentiation expression is implemented as
4477 * @refsnippet{src/scip/expr_exp.c,SnippetExprSimplifyExp}
4478 *
4479 * See also SCIPsimplifyExpr() for more information on implemented simplification rules.
4480 *
4481 * 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.
4482 * (Also bugs may show up as this situation is untested.)
4483 *
4484 * @subsection EXPRREVERSEPROP
4485 *
4486 * This callback is called when given bounds on an expression shall be propagated over the children of an expression.
4487 * Already existing bounds on the children (see \ref EXPRINTEVAL) shall be used.
4488 * That is, the method shall compute an interval overestimate on
4489 * \f[
4490 * \{ x_i : f(c_1,\ldots,c_{i-1},x_i,c_{i+1},\ldots,c_n) \in \text{bounds} \}
4491 * \f]
4492 * for each child \f$i\f$, given bounds on f and initial intervals \f$c_i, i=1,\ldots,n,\f$, for the children.
4493 *
4494 * For univariate expressions, the implementation can be rather straightforward, e.g., for absolute value:
4495 * @refsnippet{src/scip/expr_abs.c,SnippetExprReversepropAbs}
4496 *
4497 * For multivariate expressions, it can be more complicated, e.g., for products:
4498 * @refsnippet{src/scip/expr_product.c,SnippetExprReversepropProduct}
4499 *
4500 * If this callback is not implemented, the performance of domain propagation for nonlinear constraints will be impacted severely.
4501 */
4502
4503/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4504
4505/**@page NLHDLR How to add nonlinear handlers
4506 *
4507 * Nonlinear handlers define the extended formulations of nonlinear constraints and provide domain propagation and separation routines on this extended formulation.
4508 * In difference to \ref EXPRHDLR "expression handlers", they do not define a function, but instead identify a
4509 * 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.
4510 * The structure typically consists of a composition of expressions.
4511 *
4512 * Nonlinear handlers are a new plugin type in SCIP and may still have some rough edges.
4513 * They resemble constraint handlers in some sense, but are specific to the handling of nonlinear constraints.
4514 * We suggest to read section "New Handler for Nonlinear Constraints" in the SCIP 8.0 release report (2021)
4515 * to understand the role and use of nonlinear handlers before attempting to implement one.
4516 *
4517 * A complete list of all nonlinear handlers contained in this release can be found \ref NLHDLRS "here".
4518 * 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.
4519 *
4520 * Here is what you have to do to implement a nonlinear handler:
4521 * -# 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
4522 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
4523 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
4524 * -# Use `SCIPincludeNlhdlrMystruct()` in order to include the nonlinear handler into your SCIP instance, e.g., in the main file of your project. \n
4525 If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
4526 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mystruct".
4527 * -# Adjust the properties of the nonlinear handler (see \ref NLHDLR_PROPERTIES).
4528 * -# Define the nonlinear handler data and nonlinear handler expression data (see \ref NLHDLR_DATA). This is optional.
4529 * -# Implement the interface methods (see \ref NLHDLR_INTERFACE).
4530 * -# Implement the fundamental callback methods (see \ref NLHDLR_FUNDAMENTALCALLBACKS).
4531 * -# Implement the additional callback methods (see \ref NLHDLR_ADDITIONALCALLBACKS), where necessary.
4532 *
4533 * Additional documentation for the callback methods of a nonlinear handler, in particular for the input parameters,
4534 * can be found in the file \ref type_nlhdlr.h.
4535 *
4536 * @section NLHDLR_PROPERTIES Properties of a Nonlinear Handler
4537 *
4538 * At the top of the new file `nlhdlr_mystruct.c`, you can find the nonlinear handler properties.
4539 * These are given as compiler defines.
4540 * The properties you have to set have the following meaning:
4541 *
4542 * \par NLHDLR_NAME: the name of the nonlinear handler.
4543 * This name is used in the interactive shell to address the nonlinear handler.
4544 * Additionally, if you are searching for a nonlinear handler with SCIPfindNlhdlrNonlinear(), this name is looked up.
4545 * Names have to be unique: no two nonlinear handlers may have the same name.
4546 *
4547 * \par NLHDLR_DESC: the description of the nonlinear handler.
4548 * This string is printed as a description of the nonlinear handler in the interactive shell.
4549 *
4550 * \par NLHDLR_DETECTPRIORITY: the priority of the nonlinear handler when detecting structure.
4551 * This priority decides when the \ref NLHDLRDETECT callback of the nonlinear handler is called, relative to other nonlinear handlers, on an expression.
4552 * Typically, the priority should be strictly positive.
4553 * 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.
4554 *
4555 * \par NLHDLR_ENFOPRIORITY: the priority of the nonlinear handler when enforcing constraints in the extended formulations.
4556 * 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.
4557 * A high priority means that the nonlinear handler will be called before others.
4558 * The nonlinear handler "default" has enforcement priority 0.
4559 *
4560 * @section NLHDLR_DATA Nonlinear Handler Data and Nonlinear Handler Expression Data
4561 *
4562 * Below the header "Data structures" you can find structs called `struct SCIP_NlhdlrData` and `struct SCIP_NlhdlrExprData`.
4563 * In this first data structure, you can store the data of your nonlinear handler.
4564 * For example, you should store the adjustable parameters of the nonlinear handler in this data structure.
4565 * In the second data structure, you can store data that is unique to an expression for which the nonlinear handler detected a structure.
4566 * For example, the nonlinear handler for quotients stores a representation of a detected quotient in this data structure.
4567 * \n
4568 * Defining nonlinear handler data and nonlinear handler expression data is optional. You can leave these structs empty.
4569 *
4570 * @section NLHDLR_INTERFACE Interface Methods
4571 *
4572 * At the bottom of `nlhdlr_mystruct.c`, you can find the interface method `SCIPincludeNlhdlrXyz()`,
4573 * which also appears in `nlhdlr_mystruct.h`.
4574 * `SCIPincludeNlhdlrXyz()` is called by the user, if (s)he wants to include the nonlinear handler,
4575 * i.e., if (s)he wants to use the nonlinear handler in his/her application.
4576 *
4577 * This method is responsible for notifying SCIP of the presence of the nonlinear handler.
4578 * For this, you must call SCIPincludeNlhdlrNonlinear() from SCIPincludeNlhdlrMystruct().
4579 * The function only expects the properties and fundamental callbacks of the nonlinear handler as arguments.
4580 * \ref NLHDLR_ADDITIONALCALLBACKS "Additional callbacks" must be added via setter functions as, e.g., SCIPnlhdlrSetCopyHdlr().
4581 *
4582 * If you are using nonlinear handler data, you have to allocate the memory for the data at this point and initialize it.
4583 * For freeing the nonlinear handler data, see \ref NLHDLRFREEHDLRDATA.
4584 * You may also add user parameters or statistic tables for your nonlinear handler, see \ref PARAM for how to add user parameters.
4585 *
4586 * For the bilinear nonlinear handler, the include method is as follows:
4587 * @refsnippet{src/scip/nlhdlr_bilinear.c,SnippetIncludeNlhdlrBilinear}
4588 *
4589 *
4590 * @section NLHDLR_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Nonlinear Handler
4591 *
4592 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
4593 * an operational algorithm.
4594 * They are passed to SCIP when the nonlinear handler is created and included in SCIP via SCIPincludeNlhdlrNonlinear(),
4595 * see @ref NLHDLR_INTERFACE.
4596 *
4597 * Nonlinear handlers have two fundamental callbacks that need to be implemented.
4598 * Additional documentation for the callback methods, in particular to their input parameters,
4599 * can be found in \ref type_nlhdlr.h.
4600 *
4601 * @subsection NLHDLRDETECT
4602 *
4603 * This callback is called by the handler for nonlinear constraints when extended formulations are constructed.
4604 * The result of this callback determines the extended formulation.
4605 *
4606 * The nonlinear handler shall analyze the given expression (`expr`) and decide whether it wants to contribute
4607 * in enforcing the relation between bounds or an auxiliary variable (`auxvar`) associated with this expression and
4608 * its descendants (e.g., children) via linear under- or overestimation, cut generation, and/or activity computation and propagation.
4609 * For linear under- or overestimation and cut generation, an auxiliary variable can be assumed to
4610 * be associated with the expression and auxiliary variables may be requested for descendant expressions.
4611 *
4612 * We distinguish the following enforcement methods:
4613 * - \ref SCIP_NLHDLR_METHOD_SEPABELOW : linear underestimation of `expr` or cut generation for the relation `expr` &le; `auxvar` (denoted as "below")
4614 * - \ref SCIP_NLHDLR_METHOD_SEPAABOVE : linear overestimation of `expr` or cut generation for the relation `expr` &ge; `auxvar` (denoted as "above")
4615 * - \ref SCIP_NLHDLR_METHOD_ACTIVITY : domain propagation (i.e., constant under/overestimation) for `expr`.
4616 *
4617 * On input, parameter `enforcing` indicates for any of these methods, whether
4618 * - 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,
4619 * or because analysis of the expression has shown that a relation like `expr` &ge; `auxvar` is not necessary to be satisfied,
4620 * - or there already exists a nonlinear handler that will provide this method in an "enforcement" sense, that is,
4621 * 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
4622 * it should still reach out to the expression handler or whether it would be dominated by some nonlinear handler.)
4623 *
4624 * The DETECT callback shall augment the `enforcing` bitmask by setting the enforcement methods it wants to provide in an "enforcement" sense.
4625 *
4626 * Additionally, the `participating` bitmask shall be set if the nonlinear handler wants to be called on this expression at all.
4627 * Here, it shall set all methods that it wants to provide, which are those set in `enforcing`, but additionally those where it wants
4628 * to participate but leave enforcement to another nonlinear handler.
4629 * This can be useful for nonlinear handlers that do not implement a complete enforcement, e.g., a handler that only contributes
4630 * cutting planes in some situations only.
4631 *
4632 * A nonlinear handler will be called only for those callbacks that it mentioned in `participating`, which is
4633 * - \ref NLHDLRENFO and/or \ref NLHDLRESTIMATE will be called with `overestimate==FALSE` if \ref SCIP_NLHDLR_METHOD_SEPABELOW has been set
4634 * - \ref NLHDLRENFO and/or \ref NLHDLRESTIMATE will be called with `overestimate==TRUE` if \ref SCIP_NLHDLR_METHOD_SEPAABOVE has been set
4635 * - \ref NLHDLRINTEVAL and/or \ref NLHDLRREVERSEPROP will be called if \ref SCIP_NLHDLR_METHOD_ACTIVITY has been set
4636 *
4637 * If \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE has been set, then at least one of the
4638 * callbacks \ref NLHDLRENFO and \ref NLHDLRESTIMATE needs to be implemented.
4639 * Also \ref NLHDLREVALAUX will be called in this case.
4640 * If \ref SCIP_NLHDLR_METHOD_ACTIVITY has been set, then at least one of \ref NLHDLRINTEVAL and \ref NLHDLRREVERSEPROP needs to be implemented.
4641 * If the nonlinear handler chooses not to participate, then it must not set `nlhdlrexprdata` and can leave `participating` at its
4642 * initial value (\ref SCIP_NLHDLR_METHOD_NONE).
4643 *
4644 * Additionally, a nonlinear handler that decides to participate in any of the enforcement methods must call
4645 * @ref SCIPregisterExprUsageNonlinear() for every subexpression that it will use and indicate whether
4646 * - it will use an auxiliary variable in \ref NLHDLRENFO or \ref NLHDLRESTIMATE,
4647 * - it will use activity for some subexpressions when computing estimators or cuts, and
4648 * - it will use activity for some subexpressions when in \ref NLHDLRINTEVAL or \ref NLHDLRREVERSEPROP.
4649 *
4650 * Note that auxiliary variables do not exist in subexpressions during DETECT and are not created by a call to @ref SCIPregisterExprUsageNonlinear().
4651 * They will be available when the \ref NLHDLRINITSEPA callback is called.
4652 *
4653 * For an example, see the implementation of the DETECT callback for the nonlinear handler for quotients (src/scip/nlhdlr_quotient.c).
4654 *
4655 * @subsection NLHDLREVALAUX
4656 *
4657 * This callback is called by the constraint handler for nonlinear constraints when the violation of constraints in the extended formulation
4658 * (`expr` &le;/&ge; `auxvar`) needs to be evaluated.
4659 * During constraint enforcement, this violation value is used to decide whether estimation and separation callbacks should be called.
4660 *
4661 * The method shall evaluate the expression w.r.t. the auxiliary variables that were introduced by the nonlinear handler (if any).
4662 * It can be assumed that the expression itself has been evaluated in the given sol.
4663 *
4664 * For an example, see the evaluation for the quotient nonlinear handler:
4665 * @refsnippet{src/scip/nlhdlr_quotient.c,SnippetNlhdlrEvalauxQuotient}
4666*
4667 * @section NLHDLR_ADDITIONALCALLBACKS Additional Callback Methods of a Nonlinear Handler
4668 *
4669 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
4670 * implemented for most applications, they can be used, for example, to initialize and free private data.
4671 * Additional callbacks can be passed via specific
4672 * <b>setter functions</b> after a call of SCIPincludeNlhdlrNonlinear(), see also @ref NLHDLR_INTERFACE.
4673 *
4674 * @subsection NLHDLRCOPYHDLR
4675 *
4676 * This callback is called when doing a copy of the constraint handler for nonlinear constraints.
4677 * It shall include the nonlinear handler into the copy of the constraint handler.
4678 *
4679 * @subsection NLHDLRFREEHDLRDATA
4680 *
4681 * If you are using nonlinear handler data (see \ref NLHDLR_DATA and \ref NLHDLR_INTERFACE), you have to implement this method
4682 * in order to free the nonlinear handler data.
4683 *
4684 * @subsection NLHDLRFREEEXPRDATA
4685 *
4686 * If you are using nonlinear handler expression data (see \ref NLHDLR_DATA and \ref NLHDLRDETECT), you have to implement this method
4687 * in order to free the nonlinear handler expression data.
4688 * This method is called when an extended formulation is freed.
4689 *
4690 * @subsection NLHDLRINIT
4691 *
4692 * This callback is called when the constraint handler for nonlinear constraints is initialized, that is, after the problem was transformed.
4693 * The nonlinear handler can use this callback to initialize or reset some data for the upcoming solve.
4694 *
4695 * @subsection NLHDLREXIT
4696 *
4697 * This callback is called when the constraint handler for nonlinear constraints is deinitialized, that is, before the transformed problem is freed.
4698 * The nonlinear handler can use this callback to free some data that was used for the previous solve only.
4699 *
4700 * @subsection NLHDLRINTEVAL
4701 *
4702 * This callback is called when bounds on a given expression shall be computed.
4703 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_ACTIVITY in \ref NLHDLRDETECT.
4704 * The method is given the currently available bounds to the expression and can return possibly tighter bounds.
4705 *
4706 * For a univariate quotient ((ax+b)/(cx+d)), the interval evaluation is implemented as follows:
4707 * @refsnippet{src/scip/nlhdlr_quotient.c,SnippetNlhdlrIntevalQuotient}
4708 *
4709 * @subsection NLHDLRREVERSEPROP
4710 *
4711 * This callback is called when bounds on a given expression shall be propagated to its successors.
4712 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_ACTIVITY in \ref NLHDLRDETECT.
4713 * The tighter intervals should be passed to the corresponding expression via SCIPtightenExprIntervalNonlinear().
4714 *
4715 * For a univariate quotient ((ax+b)/(cx+d)), reverse propagation is implemented as follows:
4716 * @refsnippet{src/scip/nlhdlr_quotient.c,SnippetNlhdlrReversepropQuotient}
4717 *
4718 * @subsection NLHDLRINITSEPA
4719 *
4720 * This callback is called when the constraint handler for nonlinear constraints initializes the LP relaxation (@ref CONSINITLP).
4721 * 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.
4722 * The method shall initialize the separation data of the nonlinear handler, if any, and add initial cuts to the LP relaxation.
4723 * It can assume that auxiliary variables are available for expressions for which auxiliary variables were requested via SCIPregisterExprUsageNonlinear() in \ref NLHDLRDETECT.
4724 *
4725 * @subsection NLHDLREXITSEPA
4726 *
4727 * This callback is called when the solving process is finished and the branch and bound process data is freed (@ref CONSEXITSOL).
4728 * 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.
4729 * The method shall deinitialize the separation data of the nonlinear handler, if any.
4730 *
4731 * @subsection NLHDLRENFO
4732 *
4733 * This callback is called when the constraint handler requires that the relation between the given expression and its auxiliary variable
4734 * (`expr` &le; `auxvar` or `expr` &ge; `auxvar`) is violated by a given solution and this solution needs to be separated.
4735 * 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.
4736 *
4737 * The nonlinear handler can enforce `expr` &le;/&ge; `auxvar` by
4738 * - separation, i.e., finding an affine hyperplane (a cut) that separates the given point, or
4739 * - bound tightening, i.e., changing bounds on a variable so that the given point is outside the updated domain, or
4740 * - adding branching scores to potentially split the current problem into two subproblems.
4741 *
4742 * If parameter `inenforcement` is FALSE, then only the first option (separation) is allowed.
4743 *
4744 * If the nonlinear handler always separates by computing a linear under- or overestimator of `expr`,
4745 * then it is usually easier to implement the \ref NLHDLRESTIMATE callback instead.
4746 *
4747 * Note, that the nonlinear handler may also choose to separate for a relaxation of the mentioned sets,
4748 * e.g., `expr` &le; upperbound(`auxvar`) or `expr` &ge; lowerbound(`auxvar`).
4749 * This is especially useful in situations where `expr` is the root expression of a constraint
4750 * and it is sufficient to satisfy `lhs` &le; `expr` &le; `rhs`.
4751 * The constraint handler ensures that `lhs` &le; lowerbound(`auxvar`) and upperbound(`auxvar`) &le; `rhs`.
4752 *
4753 * The constraint handler may call this callback first with `allowweakcuts` = FALSE and repeat later with
4754 * `allowweakcuts` = TRUE, if it didn't succeed to enforce a solution without using weak cuts.
4755 * If in enforcement and the nonlinear handler cannot enforce by separation or bound tightening, it should register
4756 * branching scores for those expressions where branching may help to compute tighter cuts in children.
4757 *
4758 * The nonlinear handler must set `result` to \ref SCIP_SEPARATED if it added a cut,
4759 * to \ref SCIP_REDUCEDDOM if it added a bound change, and
4760 * to \ref SCIP_BRANCHED if it added branching scores.
4761 * Otherwise, it may set result to \ref SCIP_DIDNOTRUN or \ref SCIP_DIDNOTFIND.
4762 *
4763 * @subsection NLHDLRESTIMATE
4764 *
4765 * This callback is called when the constraint handler requires that the relaxation between the given expression and its auxiliary variable
4766 * (`expr` &le; `auxvar` or `expr` &ge; `auxvar`) is violated by a given solution and this solution needs to be separated.
4767 * 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.
4768 * This method is a simpler alternative to \ref NLHDLRENFO and is called if \ref NLHDLRENFO is not implemented or does not succeed.
4769 *
4770 * The method shall compute one or several linear under- or overestimator of `expr` that are as tight as possible at a given point.
4771 * If the value of the estimator in the solution is smaller (larger) than a given targetvalue
4772 * when underestimating (overestimating), then no estimator needs to be computed.
4773 * Note, that targetvalue can be infinite if any estimator will be accepted.
4774 * If successful, it shall store the estimators in the given `rowpreps` data structure and set the
4775 * `rowprep->local` flag accordingly (SCIProwprepSetLocal()).
4776 * The sidetype of a rowprep must be set to \ref SCIP_SIDETYPE_LEFT if overestimating and
4777 * \ref SCIP_SIDETYPE_RIGHT if underestimating.
4778 *
4779 * The callback may also be required to indicate for which expression a reduction in the local bounds (usually by branching) would improve the estimator.
4780 * This is done by a call to SCIPaddExprsViolScoreNonlinear().
4781 *
4782 * For the quotient nonlinear handler, the estimators are computed as follows:
4783 * @refsnippet{src/scip/nlhdlr_quotient.c,SnippetNlhdlrEstimateQuotient}
4784 *
4785 * @subsection NLHDLRSOLLINEARIZE
4786 *
4787 * 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.
4788 * The constraint handler then calls the nonlinear handlers for all expressions they currently handle.
4789 * The nonlinear handler may use this opportunity to add a cut that supports its nonlinear function in the given solution to the cutpool.
4790 * For convex functions, this may help to accellerate proving optimality for a solution found by a NLP solver.
4791 */
4792
4793/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4794
4795/**@page DIVINGHEUR How to implement a diving heuristic
4796 *
4797 * Diving heuristics are an important addon to the branch-and-cut search. A diving heuristic explores a single probing
4798 * path down the search tree. In contrast to the regular search guided by branching rule(s) and the selected
4799 * node selector, the diving is performed in an auxiliary tree originating from the focus node of the main
4800 * search tree where the heuristic was called. The advantage of this approach is that many different scoring mechanisms
4801 * can be safely tried as diving heuristic and may probably lead to better solutions. SCIP has a lot of diving heuristics
4802 * included in its default plugin set.
4803 * \n
4804 *
4805 * Since SCIP version 3.2, the diving heuristics have been redesigned to contain mainly the scoring function used by the
4806 * heuristic. In order to implement a user-defined diving heuristic, it is possible to create one (or several)
4807 * divesets that control the scoring mechanism and add them to the primal heuristic. This has the advantage that
4808 * less code is necessary to create a working diving heuristic. The SCIP statistics now also display some interesting statistics
4809 * about every diveset together in the section 'Diving Statistics'.
4810 * \n
4811 *
4812 * This page contains the necessary steps to understand and include a diveset into ones primal diving heuristic plugin. As
4813 * a prerequisite, you should understand the basic implementation steps for a primal heuristic, see \ref HEUR.
4814 * In order to make use of divesets, they must be included _after_ the primal heuristic to which they should belong
4815 * has been included, by using SCIPincludeDiveset(). This will create the data structure for the diveset and
4816 * append it to the list of divesets belonging to the heuristic, which can be retrieved later together with their number
4817 * by using SCIPheurGetDivesets() and SCIPheurGetNDivesets(), respectively. No further memory allocation or deletion is needed;
4818 * As a member of the heuristic, SCIP automatically takes care of freeing the diveset when it is exiting.
4819 * \n
4820 *
4821 * Before the inclusion, one may think of adjusting the various properties that a diveset offers to control
4822 * the behavior of the algorithm. These are subject to the following section.
4823 * \n
4824 *
4825 * It is mandatory to implement the fundamental scoring callback of the diveset, which is explained in more detail
4826 * in Section \ref DIVING_FUNDAMENTALCALLBACKS.
4827 * \n
4828 *
4829 * Once the properties have been carefully adjusted and the scoring
4830 * has been defined, use the method SCIPperformGenericDivingAlgorithm() inside the execution callback (\ref HEUREXEC) of the primal
4831 * heuristic to which the diveset belongs, after checking possible preliminaries that may not be met at all times of the search.
4832 * \n
4833 *
4834 * For a code example, we refer to \ref heur_guideddiving.h, which guides the diving into the direction of the current incumbent solution.
4835 * Before it calls SCIPperformGenericDivingAlgorithm(), it checks whether an incumbent is available, and returns if there is none.
4836 *
4837 *
4838 * @section DIVING_PARAMETERS User parameters and properties for every diveset
4839 *
4840 * Every diveset controls the diving behavior through a set of user-defined parameters, which are explained in the following:
4841 *
4842 * \par MINRELDEPTH
4843 * the minimal relative depth (to the maximum depth explored during regular search) of the current focus node to start diving
4844 *
4845 * \par MAXRELDEPTH
4846 * the maximal relative depth (to the maximum depth explored during regular search) of the current focus node to start diving
4847 *
4848 * \par MAXLPITERQUOT
4849 * maximal fraction of diving LP iterations compared to node LP iterations that this dive controller may consume
4850 *
4851 * \par MAXLPITEROFS
4852 * an additional number of allowed LP iterations
4853 *
4854 * \par MAXDIVEUBQUOT
4855 * maximal quotient (curlowerbound - lowerbound)/(cutoffbound - lowerbound)
4856 * where diving is performed (0.0: no limit)
4857 *
4858 * \par MAXDIVEAVGQUOT
4859 * maximal quotient (curlowerbound - lowerbound)/(avglowerbound - lowerbound)
4860 * where diving is performed (0.0: no limit)
4861 *
4862 * \par MAXDIVEUBQUOTNOSOL
4863 * maximal UBQUOT when no solution was found yet (0.0: no limit)
4864 *
4865 * \par MAXDIVEAVGQUOTNOSOL
4866 * maximal AVGQUOT when no solution was found yet (0.0: no limit)
4867 *
4868 * \par BACKTRACK
4869 * use one level of backtracking if infeasibility is encountered?
4870 *
4871 * \par LPRESOLVEDOMCHGQUOT
4872 * parameter to control LP resolve dynamically based on this percentage of observed bound changes relative to all variables or
4873 * the LP branching candidates (integer variables with fractional solution values) from the last node where an LP has been solved.
4874 * This property has no effect when the LPSOLVEFREQ is set to 1.
4875 *
4876 * \par LPSOLVEFREQ
4877 * 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
4878 * diveset to solve _all_ intermediate LPs) or 0 to only resolve the LP relaxation after propagation found at least a certain percentage
4879 * domain changes, see also the previous LPRESOLVEDOMCHGQUOT parameter.
4880 *
4881 * \par ONLYLPBRANCHCANDS
4882 * Set this property to TRUE if only LP branching candidates be considered for the execution of the diving algorithm instead of the slower but
4883 * more general constraint handler diving variable selection.
4884 *
4885 * \par DIVETYPES
4886 * bit mask that represents all supported dive types. Irrelevant if only LP branching candidates should be scored, otherwise, different
4887 * constraint handlers may ask the diveset if it supports their preferred divetype. See \ref type_heur.h for a list of
4888 * available dive types.
4889 *
4890 * @section DIVING_FUNDAMENTALCALLBACKS Fundamental callbacks of a diveset
4891 *
4892 * Only one callback is necessary to complete a diveset to guide the diving search performed:
4893 *
4894 * @subsection DIVESETGETSCORE
4895 *
4896 * The scoring callback expects a candidate variable and calculates a score value and a preferred direction. The selected
4897 * variable for diving will be one that _maximizes_ the score function provided by the diveset.
4898 * If the diveset should support more than one possible type of diving, it may use the divetype argument as a hint how
4899 * the caller of the score function (could be the diving algorithm itself or one of the constraint handlers that
4900 * implement diving variable selection) intends to perform the search.
4901 *
4902 * @section DIVING_FURTHERINFO Further information
4903 *
4904 * This is all there is to extend the SCIP set of diving heuristics by a new one. For further information, please see
4905 * diveset related methods in \ref type_heur.h, \ref pub_heur.h, \ref heuristics.h, and \ref heur_guideddiving.h or
4906 * other diving heuristics that implement diving through a diveset.
4907 */
4908
4909/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4910
4911/**@page RELAX How to add relaxation handlers
4912 *
4913 * SCIP provides specific support for LP relaxations of constraint integer programs. In addition, relaxation handlers,
4914 * also called relaxators, can be used to include other relaxations, e.g. Lagrange relaxations or semidefinite
4915 * relaxations. The relaxation handler manages the necessary data structures and calls the relaxation solver to generate dual
4916 * bounds and primal solution candidates.
4917 * \n
4918 * However, the data to define a single relaxation must either be extracted by the relaxation handler itself (e.g., from
4919 * the user defined problem data, the LP information, or the integrality conditions), or it must be provided by the constraint
4920 * handlers. In the latter case, the constraint handlers have to be extended to support this specific relaxation.
4921 * \n
4922 *
4923 * We now explain how users can add their own relaxation handlers using the C interface. As an example, look into the NLP
4924 * relaxation handler of the \ref RELAXATOR_MAIN "Relaxator example" (examples/Relaxator/src/relax_nlp.c). It is very easy to
4925 * transfer the C explanation to C++: whenever a method should be implemented using the SCIP_DECL_RELAX... notion,
4926 * reimplement the corresponding virtual member function of the abstract scip::ObjRelax wrapper base class.
4927 *
4928 * Additional documentation for the callback methods of a relaxation handler can be found in the file type_relax.h.
4929 *
4930 * Here is what you have to do to implement a relaxation handler:
4931 * -# Copy the template files src/scip/relax_xyz.c and src/scip/relax_xyz.h into files named "relax_myrelaxator.c"
4932 * and "relax_myrelaxator.h".
4933 * \n
4934 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
4935 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
4936 * -# Use `SCIPincludeRelaxMyrelaxator()` in order to include the relaxation handler into your SCIP instance,
4937 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
4938 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
4939 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myrelaxator".
4940 * -# Adjust the properties of the relaxation handler (see \ref RELAX_PROPERTIES).
4941 * -# Define the relaxation handler data (see \ref RELAX_DATA). This is optional.
4942 * -# Implement the interface methods (see \ref RELAX_INTERFACE).
4943 * -# Implement the fundamental callback methods (see \ref RELAX_FUNDAMENTALCALLBACKS).
4944 * -# Implement the additional callback methods (see \ref RELAX_ADDITIONALCALLBACKS). This is optional.
4945 *
4946 *
4947 * @section RELAX_PROPERTIES Properties of a Relaxation Handler
4948 *
4949 * At the top of the new file "relax_myrelaxator.c" you can find the relaxation handler properties,
4950 * which are given as compiler defines.
4951 * In the C++ wrapper class, you have to provide the relaxation handler properties by calling the constructor
4952 * of the abstract base class scip::ObjRelax from within your constructor.
4953 * The properties have the following meaning:
4954 *
4955 * \par RELAX_NAME: the name of the relaxation handler.
4956 * This name is used in the interactive shell to address the relaxation handler.
4957 * Additionally, if you are searching for a relaxation handler with SCIPfindRelax(), this name is looked up.
4958 * Names have to be unique: no two relaxation handlers may have the same name.
4959 *
4960 * \par RELAX_DESC: the description of the relaxation handler.
4961 * This string is printed as a description of the relaxation handler in the interactive shell.
4962 *
4963 * \par RELAX_PRIORITY: the priority of the relaxation handler.
4964 * During each relaxation solving round, the included relaxation handlers and the
4965 * price-and-cut loop for solving the LP relaxation are called in a predefined order, which is given by the priorities
4966 * of the relaxation handlers.
4967 * First, the relaxation handlers with non-negative priority are called in the order of decreasing priority.
4968 * Next, the price-and-cut loop for solving the LP relaxation is executed.
4969 * Finally, the relaxation handlers with negative priority are called in the order of decreasing priority.
4970 * \n
4971 * Usually, you will have only one relaxation handler in your application and thus only have to decide whether it should
4972 * be called before or after solving the LP relaxation. For this decision you should consider the complexity of
4973 * the relaxation solving algorithm and the impact of the resulting solution: if your relaxation handler provides a fast
4974 * algorithm that usually has a high impact (i.e. the relaxation is a good approximation of the
4975 * feasible region of the subproblem and the solution severely improves the dual bound), it should have a non-negative
4976 * priority.
4977 * \n
4978 * Note that for certain applications, it is useful to disable the LP relaxation and only use your custom relaxation.
4979 * This can easily be achieved by setting the "lp/solvefreq" parameter to -1.
4980 *
4981 * \par RELAX_FREQ: the default frequency for solving the relaxation.
4982 * The frequency defines the depth levels at which the relaxation solving method \ref RELAXEXEC is called.
4983 * For example, a frequency of 7 means, that the relaxation solving callback is executed for subproblems that are in depth
4984 * 0, 7, 14, ... of the branching tree. A frequency of 0 means that the callback is only executed at the root node, i.e.,
4985 * only the relaxation of the root problem is solved. A frequency of -1 disables the relaxation handler.
4986 *
4987 *
4988 *
4989 * @section RELAX_DATA Relaxation Handler Data
4990 *
4991 * Below the header "Data structures" you can find a struct which is called "struct SCIP_RelaxData".
4992 * In this data structure, you can store the data of your relaxation handler. For example, you should store the adjustable
4993 * parameters of the relaxation handler in this data structure.
4994 * If you are using C++, you can add relaxation handler data as usual as object variables to your class.
4995 * \n
4996 * Defining relaxation handler data is optional. You can leave the struct empty.
4997 *
4998 *
4999 * @section RELAX_INTERFACE Interface Methods
5000 *
5001 * At the bottom of "relax_myrelaxator.c", you can find the interface method SCIPincludeRelaxMyrelaxator(),
5002 * which also appears in "relax_myrelaxator.h".
5003 * SCIPincludeRelaxMyrelaxator() is called by the user, if (s)he wants to include the relaxation handler,
5004 * i.e., if (s)he wants to use the relaxation handler in his/her application.
5005 *
5006 * This method only has to be adjusted slightly.
5007 * It is responsible for notifying SCIP of the presence of the relaxation handler. For this, you can either call
5008 * SCIPincludeRelax(),
5009 * or SCIPincludeRelaxBasic() since SCIP version 3.0. In the latter variant, \ref RELAX_ADDITIONALCALLBACKS "additional callbacks"
5010 * must be added via setter functions as, e.g., SCIPsetRelaxCopy(). We recommend this latter variant because
5011 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
5012 * variant must be manually adjusted with every SCIP release containing new callbacks for relaxation handlers in order to compile.
5013 *
5014 * If you are using relaxation handler data, you have to allocate the memory for the data at this point.
5015 * You can do this by calling:
5016 * \code
5017 * SCIP_CALL( SCIPallocBlockMemory(scip, &relaxdata) );
5018 * \endcode
5019 * You also have to initialize the fields in struct SCIP_RelaxData afterwards.
5020 *
5021 * You may also add user parameters for your relaxation handler, see the method SCIPincludeConshdlrKnapsack() in
5022 * the \ref cons_knapsack.h "knapsack constraint handler" for an example of how to add user parameters.
5023 *
5024 *
5025 * @section RELAX_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Relaxation Handler
5026 *
5027 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
5028 * an operational algorithm.
5029 * They are passed together with the relaxation handler itself to SCIP using SCIPincludeRelax() or SCIPincludeRelaxBasic(),
5030 * see @ref RELAX_INTERFACE.
5031 *
5032 *
5033 * Relaxation handler plugins have only one fundamental callback method, namely the \ref RELAXEXEC method.
5034 * This method has to be implemented for every relaxation handler; the other callback methods are optional.
5035 * In the C++ wrapper class scip::ObjRelax, the scip_exec() method (which corresponds to the \ref RELAXEXEC callback) is a virtual
5036 * abstract member function.
5037 * You have to implement it in order to be able to construct an object of your relaxation handler class.
5038 *
5039 * Additional documentation for the callback methods can be found in type_relax.h.
5040 *
5041 * @subsection RELAXEXEC
5042 * The RELAXEXEC is called in each relaxation solving round. It should solve the current
5043 * subproblem's relaxation.
5044 *
5045 * Note that, like the LP relaxation, the relaxation handler should only operate on variables for which the corresponding
5046 * column exists in the transformed problem. Typical methods called by a relaxation handler are SCIPconstructLP() and SCIPflushLP() to
5047 * make sure that the LP of the current node is constructed and its data can be accessed via calls to SCIPgetLPRowsData()
5048 * and SCIPgetLPColsData(), and SCIPseparateSol() to call the cutting plane separators for a given primal solution.
5049 *
5050 * The lowerbound computed by the relaxation should be returned in the lowerbound pointer. If the relaxation improves on the best
5051 * relaxation already computed (either <code>SCIPisRelaxSolValid()</code> returns FALSE, meaning that no relaxation solution
5052 * is available so far, or the lowerbound is larger than the value returned by <code>SCIPgetRelaxSolObj()</code>), then the primal
5053 * solution of the relaxation should be stored inside the data structures of SCIP with <code>SCIPsetRelaxSolVal()</code>,
5054 * <code>SCIPsetRelaxSolVals()</code> or <code>SCIPsetRelaxSolValsSol()</code>. If you set the values one by one, you will need to call
5055 * <code>SCIPmarkRelaxSolValid()</code> to inform SCIP that the solution is complete and valid. With the "includeslp" argument of
5056 * <code>SCIPsetRelaxSolVals()</code>, <code>SCIPsetRelaxSolValsSol()</code> and <code>SCIPmarkRelaxSolValid()</code> you need to tell SCIP
5057 * 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
5058 * lowerbound of this relaxator is larger than the LP's. You may also call SCIPtrySolFree() directly from the
5059 * relaxation handler to make sure that a solution is added to the solution storage if it is feasible, even if the relaxator does not
5060 * include the LP or another relaxator produced a stronger bound. Also note that when setting the values of the relaxation solution one by one,
5061 * the objective value of the relaxation solution will be updated incrementally. If the whole solution should be updated, using SCIPsetRelaxSolVals()
5062 * instead or calling SCIPclearRelaxSolVals() before setting the first value to reset the solution and the objective value to 0 may help the numerics.
5063 * Furthermore, there is a list of external branching candidates, that can be filled by relaxation handlers and constraint handlers,
5064 * allowing branching rules to take these candidates as a guide on how to split the problem into subproblems. If the relaxation
5065 * solution is enforced, the integrality constraint handler will add external branching candidates for the relaxation solution
5066 * automatically, but the relaxation handler can also directly call <code>SCIPaddExternBranchCand()</code>.
5067 *
5068 * Usually, the RELAXEXEC callback only solves the relaxation and provides a lower (dual) bound through the corresponding pointer and
5069 * possibly a solution through <code>SCIPsetRelaxSolVal()</code> calls.
5070 * However, it may also produce domain reductions, add additional constraints or generate cutting planes. It has the
5071 * following options:
5072 * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
5073 * - adding an additional constraint and stating that the relaxation handler should not be called again on the same
5074 * relaxation (result SCIP_CONSADDED)
5075 * - reducing a variable's domain and stating that the relaxation handler should not be called again on the same
5076 * relaxation (result SCIP_REDUCEDDOM)
5077 * - adding a cutting plane to the LP and stating that the relaxation handler should not be called again on the same
5078 * relaxation (result SCIP_SEPARATED)
5079 * - stating that the relaxation handler solved the relaxation and should not be called again on the same relaxation
5080 * (result SCIP_SUCCESS)
5081 * - interrupting the solving process to wait for additional input, e.g., cutting planes (result SCIP_SUSPENDED)
5082 * - stating that the separator was skipped (result SCIP_DIDNOTRUN).
5083 *
5084 * In the above criteria, "the same relaxation" means that the LP relaxation stayed unmodified. This means in particular
5085 * that no row has been added and no bounds have been modified. For example, changing the bounds of a variable will, as
5086 * long as it was a COLUMN variable, lead to a modification in the LP such that the relaxation handler is called again
5087 * after it returned with the result code SCIP_REDUCEDDOM. If the relaxation solution should be enforced, the relaxation
5088 * handler has to produce a new solution in this case which satisfies the updated LP. If a relaxation handler should only run
5089 * once per node to compute a lower bound, it should store the node of the last relaxation call itself and return
5090 * SCIP_DIDNOTRUN for subsequent calls in the same node.
5091 *
5092 *
5093 * @section RELAX_ADDITIONALCALLBACKS Additional Callback Methods of a Relaxation Handler
5094 *
5095 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
5096 * implemented for most applications, they can be used, for example, to initialize and free private data.
5097 * Additional callbacks can either be passed directly with SCIPincludeRelax() to SCIP or via specific
5098 * <b>setter functions</b> after a call of SCIPincludeRelaxBasic(), see also @ref RELAX_INTERFACE.
5099 *
5100 * @subsection RELAXFREE
5101 *
5102 * If you are using relaxation handler data, you have to implement this method in order to free the relaxation handler
5103 * data. This can be done by the following procedure:
5104 *
5105 * @refsnippet{tests/src/relax/relax.c,SnippetRelaxFreeUnittest}
5106 *
5107 * If you have allocated memory for fields in your relaxation handler data, remember to free this memory
5108 * before freeing the relaxation handler data itself.
5109 * If you are using the C++ wrapper class, this method is not available.
5110 * Instead, just use the destructor of your class to free the member variables of your class.
5111 *
5112 * @subsection RELAXINIT
5113 *
5114 * The RELAXINIT callback is executed after the problem is transformed.
5115 * The relaxation handler may, e.g., use this call to initialize its relaxation handler data.
5116 *
5117 * @subsection RELAXCOPY
5118 *
5119 * The RELAXCOPY callback is executed when a SCIP instance is copied, e.g. to
5120 * solve a sub-SCIP. By
5121 * defining this callback as
5122 * <code>NULL</code> the user disables the execution of the specified
5123 * relaxation handler for all copied SCIP instances. This may deteriorate the performance
5124 * of primal heuristics using sub-SCIPs.
5125 *
5126 * @subsection RELAXEXIT
5127 *
5128 * The RELAXEXIT callback is executed before the transformed problem is freed.
5129 * In this method, the relaxation handler should free all resources that have been allocated for the solving process in
5130 * RELAXINIT.
5131 *
5132 * @subsection RELAXINITSOL
5133 *
5134 * The RELAXINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
5135 * begin. The relaxation handler may use this call to initialize its branch-and-bound specific data.
5136 *
5137 * @subsection REALXEXITSOL
5138 *
5139 * The RELAXEXITSOL callback is executed before the branch-and-bound process is freed.
5140 * The relaxation handler should use this call to clean up its branch-and-bound data.
5141 */
5142
5143/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5144
5145/**@page READER How to add file readers
5146 *
5147 * Mainly, file readers are called to parse an input file and generate a constraint integer programming model. They
5148 * create constraints and variables and activate variable pricers if necessary. However, they can also be called, for
5149 * example, to parse an input file containing information about a primal solution or fixing of variables. Besides that
5150 * it is possible to use some of them for writing (exporting) the problem in a specific format. \n A complete list of
5151 * all file readers contained in this release can be found \ref FILEREADERS "here".
5152 *
5153 * Since a file reader is also responsible for writing a file, the user may
5154 * ask why the readers have not the name "filehandler". This name would
5155 * represent this plugin much better than the used one.
5156 * \n
5157 * The used name "readers" is historically grown. In the beginning of SCIP
5158 * there was no need to write/export problems. Therefore, the the plugin
5159 * name "readers" was best fitting for this plugin since only reading was essential.
5160 * It turned out, however, that it is quite nice to write/export certain subproblem during
5161 * the solving process mainly for debugging. Therefore, a writing callback
5162 * was added to the "readers" plugin.
5163 *
5164 * We now explain how users can add their own file readers.
5165 * Take the file reader for MIPs in IBM's Mathematical Programming System format (src/scip/reader_mps.c) as an example.
5166 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjReader wrapper
5167 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_READER... callback methods.
5168 *
5169 * Additional documentation for the callback methods of a file reader can be found in the file type_reader.h.
5170 *
5171 * Here is what you have to do to implement a file reader named "myreader" in C:
5172 * -# Copy the template files src/scip/reader_xyz.c and src/scip/reader_xyz.h into files named
5173 * "reader_myreader.c" and "reader_myreader.h".
5174 * \n
5175 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5176 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5177 * -# Use `SCIPincludeReaderMyreader()` in order to include the reader into your SCIP instance,
5178 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5179 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5180 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myreader".
5181 * -# Adjust the \ref READER_PROPERTIES "properties of the file reader".
5182 * -# Define the \ref READER_DATA "file reader data". This is optional.
5183 * -# Implement the \ref READER_INTERFACE "interface methods".
5184 * -# Implement the \ref READER_FUNDAMENTALCALLBACKS "fundamental callback methods".
5185 * -# Implement the \ref READER_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5186 *
5187 *
5188 * @section READER_PROPERTIES Properties of a File Reader
5189 *
5190 * At the top of the new file "reader_myreader.c" you can find the file reader properties.
5191 * These are given as compiler defines.
5192 * In the C++ wrapper class, you have to provide the file reader properties by calling the constructor
5193 * of the abstract base class scip::ObjReader from within your constructor.
5194 * The properties you have to set have the following meaning:
5195 *
5196 * \par READER_NAME: the name of the file reader.
5197 * This name is used in the interactive shell to address the file reader.
5198 * Additionally, if you are searching for a file reader with SCIPfindReader(), this name is looked up.
5199 * Names have to be unique: no two file readers may have the same name.
5200 *
5201 * \par READER_DESC: the description of the file reader.
5202 * This string is printed as a description of the file reader in the interactive shell.
5203 *
5204 * \par READER_EXTENSION: the file name extension of the file reader.
5205 * Each file reader is hooked to a single file name extension. It is automatically called if the user wants to read in a
5206 * file of corresponding name. The extensions of the different file readers have to be unique.
5207 * Note that the additional extension '.gz', '.z', or '.Z' (indicating a gzip compressed file) are ignored for assigning
5208 * an input file to a reader.
5209 * \n
5210 * It is not possible to hook up a (single) file reader with more than one file extension.
5211 * It is, however, not necessary to implement the same (parsing/writing) methods more than once, if you want to
5212 * support several file extension with the same parser. To do so look at the files reader_lp.c
5213 * and reader_rlp.c. Both support the LP format.
5214 *
5215 *
5216 * @section READER_DATA File Reader Data
5217 *
5218 * Below the header "Data structures" you can find a struct which is called "struct SCIP_ReaderData".
5219 * In this data structure, you can store the data of your file reader. For example, you should store the adjustable
5220 * parameters of the file reader in this data structure.
5221 * If you are using C++, you can add file reader data as usual as object variables to your class.
5222 * \n
5223 * Defining file reader data is optional. You can leave the struct empty.
5224 *
5225 *
5226 * @section READER_INTERFACE Interface Methods
5227 *
5228 * At the bottom of "reader_myreader.c", you can find the interface method SCIPincludeReaderMyreader(),
5229 * which also appears in "reader_myreader.h".
5230 * SCIPincludeReaderMyreader() is called by the user, if (s)he wants to include the reader,
5231 * i.e., if (s)he wants to use the reader in his/her application.
5232 *
5233 * This method only has to be adjusted slightly.
5234 * It is responsible for notifying SCIP of the presence of the reader. For this, you can either call
5235 * SCIPincludeReader(),
5236 * or SCIPincludeReaderBasic() since SCIP version 3.0. In the latter variant, \ref READER_ADDITIONALCALLBACKS "additional callbacks"
5237 * must be added via setter functions as, e.g., SCIPsetReaderCopy(). We recommend this latter variant because
5238 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
5239 * variant must be manually adjusted with every SCIP release containing new callbacks for readers in order to compile.
5240 *
5241 * If you are using file reader data, you have to allocate the memory for the data at this point.
5242 * You can do this by calling:
5243 * \code
5244 * SCIP_CALL( SCIPallocBlockMemory(scip, &readerdata) );
5245 * \endcode
5246 * You also have to initialize the fields in struct SCIP_ReaderData afterwards.
5247 *
5248 * You may also add user parameters for your file reader, see the method SCIPincludeReaderLp() in
5249 * src/scip/reader_lp.c for an example.
5250 *
5251 *
5252 * @section READER_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a File Reader
5253 *
5254 * File reader plugins have no fundamental callback methods. This is due to
5255 * the fact that a file reader can be used for reading and/or writing a
5256 * file. A file reader is only useful if the reader method \ref READERREAD
5257 * and/or the writing method \ref READERWRITE is implemented. One of these
5258 * methods should be implemented for every file reader; the other callback
5259 * methods \ref READERCOPY and \ref READERFREE are optional. In the C++ wrapper class scip::ObjReader, the
5260 * scip_read() and scip_write() methods (which corresponds to the \ref
5261 * READERREAD and \ref READERWRITE callback) are virtual member
5262 * functions. At least one of them should be implemented.
5263 *
5264 * Additional documentation for the callback methods can be found in type_reader.h.
5265 *
5266 *
5267 * @section READER_ADDITIONALCALLBACKS Additional Callback Methods of a File Reader
5268 *
5269 * Additional callbacks can either be passed directly with SCIPincludeReader() to SCIP or via specific
5270 * <b>setter functions</b> after a call of SCIPincludeReaderBasic(), see also @ref READER_INTERFACE.
5271 *
5272 *
5273 * File reader plugins contain only additional callback methods, namely the methods \ref READERREAD,
5274 * \ref READERWRITE, \ref READERFREE, and \ref READERCOPY. Therefore, these are not needed to be implemented. However,
5275 * at least \ref READERREAD and/or \ref READERWRITE should be implemented (see notes
5276 * \ref READER_FUNDAMENTALCALLBACKS "above").
5277 *
5278 *
5279 * @subsection READERREAD
5280 *
5281 * The READERREAD callback is called when the user invokes SCIP to read in a file with file name extension
5282 * corresponding to the READER_EXTENSION property of the file reader. This is usually triggered by a call to the method
5283 * SCIPreadProb() or by an interactive shell command.
5284 * The READERREAD callback should parse the input file and perform the desired action, which usually means
5285 * generating a constraint integer programming model, adding a primal solution, fixing variables
5286 * in an existing model.
5287 * \n
5288 * Typical methods called by a file reader that is used to read/generate constraint
5289 * integer programming models are, for example,
5290 *
5291 * - creating an empty problem: SCIPcreateProb()
5292 * - creating the variables: SCIPcreateVar(), SCIPchgVarType(), SCIPchgVarLb(), SCIPchgVarUb(), SCIPaddVar(), and
5293 * SCIPreleaseVar()
5294 * - modifying the objective function: SCIPchgVarObj() and SCIPsetObjsense().
5295 * - creating the constraints: SCIPcreateConsLinear(), SCIPaddCoefLinear(), SCIPchgLhsLinear(), SCIPchgRhsLinear(),
5296 * SCIPaddCons(), and SCIPreleaseCons()
5297 *
5298 * Primal solutions can only be created for the transformed problem. Therefore, the user has to call SCIPtransformProb()
5299 * before (s)he reads in the file containing the solution and adds it to the solution pool via the method SCIPreadSol().
5300 *
5301 *
5302 * @subsection READERWRITE
5303 *
5304 * The READERWRITE callback is called when the user invokes SCIP to write a problem (original or transformed)
5305 * in the format the reader supports. This is only possible if this callback is implemented. To write the problem
5306 * all necessary information is given through the parameters of this callback method (see type_reader.h). This
5307 * information should be used to output the problem in the requested format. This callback method is usually
5308 * triggered by the call of the methods SCIPwriteOrigProblem(), SCIPwriteTransProblem(), SCIPprintOrigProblem(),
5309 * or SCIPprintTransProblem().
5310 * \n
5311 * A typical method called by a file reader which is used to write/export a constraint
5312 * integer programming model is SCIPinfoMessage(). This method outputs a given string into a file
5313 * or into stdout.
5314 * \n
5315 * For an example we refer to the writing method of the MPS reader (see reader_mps.c).
5316 *
5317 *
5318 * @subsection READERCOPY
5319 *
5320 * The READERCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
5321 * callback as <code>NULL</code> the user disables the execution of the specified reader for all copied SCIP
5322 * instances. The question might arise why to copy that plugin. In case of debugging it is nice to be able to
5323 * write/display the copied instances. Since the reader is in charge of that, you might want to copy the plugin. Below
5324 * you see a standard implementation.
5325 *
5326 * @refsnippet{src/scip/reader_mps.c,SnippetReaderCopyMps}
5327 *
5328 * @subsection READERFREE
5329 *
5330 * If you are using file reader data, you have to implement this method in order to free the file reader data.
5331 * This can be done by the following procedure:
5332 *
5333 * @refsnippet{src/scip/reader_mps.c,SnippetReaderFreeMps}
5334 *
5335 * If you have allocated memory for fields in your file reader data, remember to free this memory
5336 * before freeing the file reader data itself.
5337 * If you are using the C++ wrapper class, this method is not available.
5338 * Instead, just use the destructor of your class to free the member variables of your class.
5339 *
5340 */
5341
5342/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5343
5344/**@page DIALOG How to add dialogs
5345 *
5346 * SCIP comes with a command line shell which allows the user to read in problem instances, modify the solver's
5347 * parameters, initiate the optimization and display certain statistics and solution information. This shell consists
5348 * of dialogs, which are organized as a tree in SCIP. A node of this tree which is not a leaf represents a menu in
5349 * the shell and the children of this node correspond to the entries of this menu (which can again be menus). All
5350 * different dialogs are managed by a dialog handler, which, in particular, is responsible for executing the dialog
5351 * corresponding to the user's command in the shell. The concept of a dialog handler is different to that
5352 * of a constraint handler, which is used to manage objects of the same structure, see \ref CONS. In particular, SCIP
5353 * features only one dialog handler (dialog_default.h), whereas there may exist different constraint handlers.
5354 * \n
5355 * A complete list of all dialogs contained in this release can be found \ref DIALOGS "here".
5356 *
5357 * We now explain how users can extend the interactive shell by adding their own dialog.
5358 * We give the explanation for creating your own source file for each additional dialog. Of course, you can collect
5359 * different dialogs in one source file. Take src/scip/dialog_default.c, where all default dialog plugins are collected, as an
5360 * example.
5361 * As all other default plugins, the default dialog plugin and the template dialog are written in C. C++ users can easily
5362 * adapt the code by using the scip::ObjDialog wrapper base class and implement the scip_...() virtual methods instead of the
5363 * SCIP_DECL_DIALOG... callback methods.
5364 *
5365 * Additional documentation for the callback methods of a dialog can be found in the file type_dialog.h.
5366 *
5367 * Here is what you have to do to add a dialog (assuming your dialog is named "mydialog"):
5368 * -# Copy the template files src/scip/dialog_xyz.c and src/scip/dialog_xyz.h into files named "dialog_mydialog.c"
5369 * and "dialog_mydialog.h".
5370 * \n
5371 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5372 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5373 * -# Use `SCIPincludeDialogMydialog()` in order to include the dialog handler into your SCIP instance,
5374 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5375 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5376 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mydialog".
5377 * -# Adjust the \ref DIALOG_PROPERTIES "properties of the dialog".
5378 * -# Define the \ref DIALOG_DATA "dialog data". This is optional.
5379 * -# Implement the \ref DIALOG_INTERFACE "interface methods".
5380 * -# Implement the \ref DIALOG_FUNDAMENTALCALLBACKS "fundamental callback methods".
5381 * -# Implement the \ref DIALOG_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5382 *
5383 *
5384 * @section DIALOG_PROPERTIES Properties of a Dialog
5385 *
5386 * At the top of the new file "dialog_mydialog.c" you can find the dialog properties.
5387 * These are given as compiler defines.
5388 * In the C++ wrapper class, you have to provide the dialog properties by calling the constructor
5389 * of the abstract base class scip::ObjDialog from within your constructor.
5390 * The properties you have to set have the following meaning:
5391 *
5392 * \par DIALOG_NAME: the name of the dialog.
5393 * In the interactive shell, this name appears as the command name of the dialog in the parent dialog.
5394 * Additionally, if you are searching an entry in a menu with SCIPdialogFindEntry(), this name is looked up.
5395 * Names within one menu have to be unique: no two dialogs in the same menu may have the same name.
5396 *
5397 * \par DIALOG_DESC: the description of the dialog.
5398 * This string is printed as a description of the dialog in the interactive shell if the additional
5399 * callback method \ref DIALOGDESC is not implemented.
5400 *
5401 * \par DIALOG_ISSUBMENU: whether the dialog is a (sub)menu.
5402 * This parameter states whether the dialog is a menu in the interactive shell, i.e., is the parent of further
5403 * dialogs.
5404 *
5405 *
5406 * @section DIALOG_DATA Dialog Data
5407 *
5408 * Below the header "Data structures" you can find a struct which is called "struct SCIP_DialogData".
5409 * In this data structure, you can store the data of your dialog.
5410 * If you are using C++, you can add dialog data as usual as object variables to your class.
5411 * \n
5412 * Defining dialog data is optional. You can leave the struct empty.
5413 *
5414 *
5415 * @section DIALOG_INTERFACE Interface Methods
5416 *
5417 * At the bottom of "dialog_mydialog.c" you can find the interface method SCIPincludeDialogMydialog(), which also appears
5418 * in "dialog_mydialog.h".
5419 * \n
5420 * This method only has to be adjusted slightly.
5421 * It is responsible for notifying SCIP of the presence of the dialog, which can be done by the following lines of code:
5422 *
5423 * @refsnippet{src/scip/dialog_xyz.c,SnippetDialogAddXyz}
5424 *
5425 * Here "parentdialog" has to be an existing dialog which is defined to be a menu (see DIALOG_ISSUBMENU), e.g.,
5426 * the default root dialog. The method SCIPgetRootDialog() returns the root dialog.
5427 *
5428 * 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
5429 * his/her application.
5430 * Note that in order to be able to link the new dialog to an existing default dialog
5431 * (except the root dialog) it has to be included <b>after the
5432 * default dialogs plugin</b>, i.e., the SCIPincludeDialogMydialog() call has to occur after the
5433 * SCIPincludeDialogDefault() call. The SCIPincludeDialogDefault() method is called from within the SCIPincludeDefaultPlugins()
5434 * method. Therefore, it suffices to include your dialog plugins after you have called SCIPincludeDefaultPlugins().
5435 * In case you want to add a dialog to the <b>root dialog</b>, you just use the following
5436 * lines of code to get/create the root dialog.
5437 *
5438 * @refsnippet{tests/src/misc/snippets.c,SnippetDialogCreate}
5439 *
5440 * Therefore, in this case you do not have to worry about the calls of
5441 * SCIPincludeDialogDefault() and SCIPincludeDefaultPlugins() .
5442 *
5443 * If you are using dialog data, you have to allocate the memory for the data at this point.
5444 * You can do this by calling:
5445 * \code
5446 * SCIP_CALL( SCIPallocBlockMemory(scip, &dialogdata) );
5447 * \endcode
5448 * You also have to initialize the fields in struct SCIP_DialogData afterwards.
5449 *
5450 * Consider the following example. The user wants to add a "drawgraph" command to the root menu of SCIP.
5451 * (S)he copies the "dialog_xyz.c" and "dialog_xyz.h" files into files "dialog_drawgraph.c" and "dialog_drawgraph.h", respectively.
5452 * Then, (s)he puts the following code into the SCIPincludeDialogDrawgraph() method, compare SCIPincludeDialogDefault() in
5453 * src/scip/dialog_default.c:
5454 * @refsnippet{tests/src/misc/snippets.c,SnippetDialogInclude}
5455 *
5456 * Using this code, it is even possible to call SCIPincludeDialogDrawgraph() before including the default dialog plugins,
5457 * and you can also call it multiple times without causing inconsistencies in the dialog structure.
5458 *
5459 *
5460 * @section DIALOG_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Dialog
5461 *
5462 * Dialogs have only one fundamental callback method, namely the \ref DIALOGEXEC method.
5463 * This method has to be implemented for every dialog; the other callback methods are optional.
5464 * In the C++ wrapper class scip::ObjDialog, the scip_exec() method (which corresponds to the \ref DIALOGEXEC callback) is a virtual
5465 * abstract member function.
5466 * You have to implement it in order to be able to construct an object of your dialog class.
5467 *
5468 * Additional documentation for the callback methods can be found in type_dialog.h.
5469 *
5470 * @subsection DIALOGEXEC
5471 *
5472 * The DIALOGEXEC method is invoked, if the user selected the dialog's command name in the parent's menu. It should
5473 * execute what is stated in DIALOG_DESC, e.g., the display constraint handlers dialog should display information about
5474 * the constraint handlers included in SCIP, see src/scip/dialog_default.c.
5475 *
5476 * For typical methods called by the execution method, have a look at src/scip/dialog_default.c.
5477 *
5478 * The callback has to return which dialog should be processed next. This can be, for example, the root dialog
5479 * (SCIPdialoghdlrGetRoot()), the parent dialog (SCIPdialogGetParent()) or NULL, which stands for closing the interactive
5480 * shell.
5481 *
5482 *
5483 * @section DIALOG_ADDITIONALCALLBACKS Additional Callback Methods of a Dialog
5484 *
5485 * The additional callback methods do not need to be implemented in every case.
5486 * They can be used, for example, to free private data.
5487 *
5488 * @subsection DIALOGFREE
5489 *
5490 * If you are using dialog data, you have to implement this method in order to free the dialog data.
5491 * This can be done by the following procedure:
5492 * @refsnippet{tests/src/misc/snippets.c,SnippetDialogFree}
5493 *
5494 * If you have allocated memory for fields in your dialog data, remember to free this memory
5495 * before freeing the dialog data itself.
5496 * If you are using the C++ wrapper class, this method is not available.
5497 * Instead, just use the destructor of your class to free the member variables of your class.
5498 *
5499 * @subsection DIALOGDESC
5500 *
5501 * This method is called when the help menu of the parent is displayed. It should output (usually a single line of)
5502 * information describing the meaning of the dialog.
5503 * \n
5504 * If this callback is not implemented, the description string of the dialog (DIALOG_DESC) is displayed instead.
5505 *
5506 * @subsection DIALOGCOPY
5507 *
5508 * The DIALOGCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
5509 * callback as <code>NULL</code> the user disables the execution of this dialog for all copied SCIP instances. In
5510 * general there is no need to copy any dialog since it is most unlikely to start the interactive shell of the copied
5511 * instances.
5512 *
5513 */
5514
5515/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5516
5517/**@page DISP How to add display columns
5518 *
5519 * While solving a constraint integer program, SCIP displays status information in a column-like fashion. The current
5520 * number of processed branching tree nodes, the solving time, and the relative gap between primal and dual bound are
5521 * examples of such display columns. There already exists a wide variety of display columns which can be activated or
5522 * deactivated on demand, see src/scip/disp_default.c. Additionally, the user can implement his/her own display columns
5523 * in order to track problem or algorithm specific values.
5524 * \n
5525 * A complete list of all displays contained in this release can be found \ref DISPLAYS "here".
5526 *
5527 * We now explain how users can add their own display columns.
5528 * We give the explanation for creating your own source file for each additional display column. Of course, you can collect
5529 * different additional display columns in one source file.
5530 * Take src/scip/disp_default.c, where all default display columns are collected, as an example.
5531 * As all other default plugins, the default display column plugins and the display column template are written in C.
5532 * C++ users can easily adapt the code by using the scip::ObjDisp wrapper base class and implement the scip_...() virtual methods
5533 * instead of the SCIP_DECL_DISP... callback methods.
5534 *
5535 *
5536 * Additional documentation for the callback methods of a display column can be found in the file type_disp.h.
5537 *
5538 * Here is what you have to do to implement a display column (assuming your display column is named "mydisplaycolumn"):
5539 * -# Copy the template files src/scip/disp_xyz.c and src/scip/disp_xyz.h into files named "disp_mydisplaycolumn.c"
5540 * and "disp_mydisplaycolumn.h".
5541 \n
5542 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5543 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5544 * -# Use `SCIPincludeDispMydisplaycolumn()` in order to include the display column into your SCIP instance,
5545 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5546 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5547 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mydisplaycolumn".
5548 * -# Adjust the \ref DISP_PROPERTIES "properties of the display column".
5549 * -# Define the \ref DISP_DATA "display column data". This is optional.
5550 * -# Implement the \ref DISP_INTERFACE "interface methods".
5551 * -# Implement the \ref DISP_FUNDAMENTALCALLBACKS "fundamental callback methods".
5552 * -# Implement the \ref DISP_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5553 *
5554 *
5555 * @section DISP_PROPERTIES Properties of a Display Column
5556 *
5557 * At the top of the new file "disp_mydisplaycolumn.c" you can find the display column properties.
5558 * These are given as compiler defines.
5559 * In the C++ wrapper class, you have to provide the display column properties by calling the constructor
5560 * of the abstract base class scip::ObjDisp from within your constructor.
5561 * The properties you have to set have the following meaning:
5562 *
5563 * \par DISP_NAME: the name of the display column.
5564 * This name is used in the interactive shell to address the display column.
5565 * Additionally, if you are searching for a display column with SCIPfindDisp(), this name is looked up.
5566 * Names have to be unique: no two display columns may have the same name.
5567 *
5568 * \par DISP_DESC: the description of the display column.
5569 * This string is printed as a description of the display column in the interactive shell.
5570 *
5571 * \par DISP_HEADER: the header of the display column.
5572 * This string is printed as the header of the display column in the status information display.
5573 *
5574 * \par DISP_WIDTH: the width of the display column.
5575 * This parameter defines the width (number of characters) of the display column. The value of the parameter has to be
5576 * greater than or equal to the number of characters in the header string.
5577 *
5578 * \par DISP_PRIORITY: the priority of the display column.
5579 * The total width of status information lines is bounded by the parameter "display width". The display columns actually contained
5580 * in the status information display are selected in decreasing order of their priority. Furthermore, the user can force
5581 * columns to be displayed or not to be displayed in the status information display. For that, (s)he has to switch the value
5582 * of the display column's parameter "active" from "auto" (its default value) to "on" or "off", respectively.
5583 *
5584 * \par DISP_POSITION: the relative position of the display column.
5585 * In the status information display, the display columns are arranged from left to right in increasing order of their
5586 * relative position.
5587 *
5588 * \par DISP_STRIPLINE: the default for whether the display column should be separated with a line from its right neighbor.
5589 * This parameter states whether the display column should be separated with the string "|" from its right neighbor. In so
5590 * doing, the clearness of the status information display may improve.
5591 *
5592 * @section DISP_DATA Display Column Data
5593 *
5594 * Below the header "Data structures" you can find a struct which is called "struct SCIP_DispData".
5595 * In this data structure, you can store the data of your display column. For example, you should store the adjustable
5596 * parameters of the display column in this data structure.
5597 * If you are using C++, you can add display column data as usual as object variables to your class.
5598 * \n
5599 * Defining display column data is optional. You can leave the struct empty.
5600 *
5601 *
5602 * @section DISP_INTERFACE Interface Methods
5603 *
5604 * At the bottom of "disp_mydisplaycolumn.c" you can find the interface method SCIPincludeDispMydisplaycolumn(), which also
5605 * appears in "disp_mydisplaycolumn.h".
5606 * \n
5607 * This method only has to be adjusted slightly.
5608 * It is responsible for notifying SCIP of the presence of the display column by calling the method
5609 * SCIPincludeDisp().
5610 *
5611 * 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
5612 * application.
5613 *
5614 * If you are using display column data, you have to allocate the memory for the data at this point.
5615 * You can do this by calling:
5616 * \code
5617 * SCIP_CALL( SCIPallocBlockMemory(scip, &dispdata) );
5618 * \endcode
5619 * You also have to initialize the fields in struct SCIP_DispData afterwards.
5620 *
5621 * Although this is very uncommon, you may also add user parameters for your display column, see the method
5622 * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
5623 *
5624 *
5625 * @section DISP_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Display Column
5626 *
5627 * Display column plugins have only one fundamental callback method, namely the \ref DISPOUTPUT method.
5628 * This method has to be implemented for every display column; the other callback methods are optional.
5629 * In the C++ wrapper class scip::ObjDisp, the scip_output() method (which corresponds to the \ref DISPOUTPUT callback) is a virtual
5630 * abstract member function.
5631 * You have to implement it in order to be able to construct an object of your display column class.
5632 *
5633 * Additional documentation for the callback methods can be found in type_disp.h.
5634 *
5635 * @subsection DISPOUTPUT
5636 *
5637 * The DISPOUTPUT callback is called after each pricing loop during node processing and after a node has been processed.
5638 * In addition, at the root node, the callback is executed after each iteration of the price-and-cut loop.
5639 * It should write the display column information for the current node to a given output file stream.
5640 *
5641 * Typical methods called by a display column are, for example, SCIPdispLongint(), SCIPdispInt(), SCIPdispTime(), and
5642 * SCIPinfoMessage().
5643 *
5644 *
5645 * @section DISP_ADDITIONALCALLBACKS Additional Callback Methods of a Display Column
5646 *
5647 * The additional callback methods do not need to be implemented in every case.
5648 * They can be used, for example, to initialize and free private data.
5649 *
5650 * @subsection DISPCOPY
5651 *
5652 * The DISPCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this callback
5653 * as <code>NULL</code> the user disables the execution of the specified column. In general it is probably not needed to
5654 * implement that callback since the output of the copied instance is usually suppressed. In the other case or for
5655 * debugging the callback should be implement.
5656 *
5657 *
5658 * @subsection DISPFREE
5659 *
5660 * If you are using display column data, you have to implement this method in order to free the display column data.
5661 * This can be done by the following procedure:
5662 * @refsnippet{tests/src/misc/snippets.c,SnippetDispFree}
5663 *
5664 * If you have allocated memory for fields in your display column data, remember to free this memory
5665 * before freeing the display column data itself.
5666 * If you are using the C++ wrapper class, this method is not available.
5667 * Instead, just use the destructor of your class to free the member variables of your class.
5668 *
5669 * @subsection DISPINIT
5670 *
5671 * The DISPINIT callback is executed after the problem is transformed.
5672 * The display column may, e.g., use this call to initialize its display column data.
5673 *
5674 * @subsection DISPEXIT
5675 *
5676 * The DISPEXIT callback is executed before the transformed problem is freed.
5677 * In this method, the display column should free all resources that have been allocated for the solving process in
5678 * \ref DISPINIT.
5679 *
5680 * @subsection DISPINITSOL
5681 *
5682 * The DISPINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
5683 * begin. The display column may use this call to initialize its branch-and-bound specific data.
5684 *
5685 * @subsection DISPEXITSOL
5686 *
5687 * The DISPEXITSOL callback is executed before the branch-and-bound process is freed. The display column should use this
5688 * call to clean up its branch-and-bound specific data.
5689 */
5690
5691/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5692
5693/**@page EVENT How to add event handler
5694 *
5695 * While solving a constraint integer program, SCIP drops thousands of events such as SCIP_EVENTTYPE_VARFIXED (a
5696 * complete list of all events is given in type_event.h). These events can be caught and used to do something after a
5697 * certain event happens. Events can be used to speed up the solution process. For example, the set partitioning
5698 * constraint is only worth propagating if one of the involved variables is fixed. This can be detected by
5699 * catching the event SCIP_EVENTTYPE_VARFIXED. To be able to catch an event it is necessary to write an event handler
5700 * which defines what to do after a certain event was caught.
5701 *
5702 * We now explain how users can add their own event handlers. We give the explanation for creating your own
5703 * source file for each additional event handler. Of course, you can collect different event handlers in one source file
5704 * or you can put the event handler directly into the constraint handler. In a \ref EVENTUSAGE "second step" we discuss
5705 * the usage of an event handler. This means how to catch and drop events. \ref EVENTTYPES "Finally", we give some notes on the existing
5706 * types of events.
5707 *
5708 * Take src/scip/cons_logior.c, where the event handler is directly included into the constraint handler. As all other
5709 * default plugins, the event handlers are written in C. C++ users can easily adapt the code by using the scip::ObjEventhdlr
5710 * wrapper base class and implement the scip_...() virtual methods instead of the SCIP_DECL_EVENT... callback methods.
5711 *
5712 * Additional documentation for the callback methods of an event handler can be found in the file type_event.h. There is
5713 * also an example written in C which deals with an event handler. You find this example in the directory
5714 * "examples/Eventhdlr/". An C++ example can be found within the TSP project (examples/TSP/src/EventhdlrNewSol.cpp).
5715 *
5716 * Here is what you have to do to implement an event handler (assuming your event handler is named "bestsol"):
5717 * -# Copy the template files src/scip/event_xyz.c and src/scip/event_xyz.h into files named "event_bestsol.c"
5718 * and "event_bestsol.h".
5719 \n
5720 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5721 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5722 * -# Use `SCIPincludeEventBestsol()` in order to include the event handler into your SCIP instance,
5723 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5724 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5725 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "bestsol".
5726 * -# Adjust the \ref EVENTHDLR_PROPERTIES "properties of the event handler".
5727 * -# Implement the \ref EVENT_INTERFACE "interface methods".
5728 * -# Implement the \ref EVENT_FUNDAMENTALCALLBACKS "fundamental callback methods".
5729 * -# Implement the \ref EVENT_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5730 *
5731 *
5732 * @section EVENTHDLR_PROPERTIES Properties of a Event Handler
5733 *
5734 * At the top of the new file "event_bestsol.c" you can find the event handler properties.
5735 * These are given as compiler defines.
5736 * In the C++ wrapper class, you have to provide the event handler properties by calling the constructor
5737 * of the abstract base class scip::ObjEventhdlr from within your constructor.
5738 * The properties you have to set have the following meaning:
5739 *
5740 * \par EVENT_NAME: the name of the event handler.
5741 * This name has to be unique with respect to all other event handlers. If you are searching for an event handler with
5742 * SCIPfindEventhdlr(), this name is looked up.
5743 *
5744 * \par EVENT_DESC: the description of the event handler.
5745 * This string is printed as a description of the event handler.
5746 *
5747 * @section EVENTHDLR_DATA Event Handler Data
5748 *
5749 * Below the header "Data structures" you can find a struct which is called "struct SCIP_EventhdlrData".
5750 * In this data structure, you can store the data of your event handler. For example, you should store the adjustable
5751 * parameters of the event handler in this data structure.
5752 * If you are using C++, you can add event handler data as usual as object variables to your class.
5753 * \n
5754 * Defining event handler data is optional. You can leave the struct empty.
5755 *
5756 *
5757 * @section EVENT_INTERFACE Interface Methods
5758 *
5759 * At the bottom of "event_bestsol.c", you can find the interface method SCIPincludeEventBestsol(),
5760 * which also appears in "event_bestsol.h".
5761 * SCIPincludeEventBestsol() is called by the user, if (s)he wants to include the event handler,
5762 * i.e., if (s)he wants to use the event handler in his/her application.
5763 *
5764 * This method only has to be adjusted slightly.
5765 * It is responsible for notifying SCIP of the presence of the event handler. For this, you can either call
5766 * SCIPincludeEventhdlr(),
5767 * or SCIPincludeEventhdlrBasic() since SCIP version 3.0. In the latter variant, \ref EVENT_ADDITIONALCALLBACKS "additional callbacks"
5768 * must be added via setter functions as, e.g., SCIPsetReaderCopy(). We recommend this latter variant because
5769 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
5770 * variant must be manually adjusted with every SCIP release containing new callbacks for event handlers in order to compile.
5771 *
5772 * If you are using event handler data, you have to allocate the memory for the data at this point.
5773 * You can do this by calling:
5774 * \code
5775 * SCIP_CALL( SCIPallocBlockMemory(scip, &eventhdlrdata) );
5776 * \endcode
5777 * You also have to initialize the fields in struct SCIP_EventhdlrData afterwards.
5778 *
5779 * Although this is very uncommon, you may also add user parameters for your event handler, see the method
5780 * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
5781 *
5782 *
5783 * @section EVENT_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Event Handler
5784 *
5785 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
5786 * an operational algorithm.
5787 * They are passed together with the event handler itself to SCIP using SCIPincludeEventhdlr() or SCIPincludeEventhdlrBasic(),
5788 * see @ref EVENT_INTERFACE.
5789 *
5790 *
5791 * Event handler plugins have only one fundamental callback method, namely the \ref EVENTEXEC method. This method has
5792 * to be implemented for every event handler; the other callback methods are optional. In the C++ wrapper class
5793 * scip::ObjEventhdlr, the scip_exec() method (which corresponds to the \ref EVENTEXEC callback) is a virtual abstract member
5794 * function. You have to implement it in order to be able to construct an object of your event handler class.
5795 *
5796 * Additional documentation for the callback methods can be found in type_event.h.
5797 *
5798 * @subsection EVENTEXEC
5799 *
5800 * The EVENTEXEC callback is called after the requested event happened. Then the event handler can do some action in
5801 * reaction to the event.
5802 *
5803 * Typical the execution method sets a parameter to TRUE to indicate later in solving process that something happened
5804 * which should be analyzed further. In the \ref cons_knapsack.h "knapsack constraint handler" you find such a typical
5805 * example.
5806 *
5807 * @section EVENT_ADDITIONALCALLBACKS Additional Callback Methods of a Event Handler
5808 *
5809 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
5810 * implemented for most applications, they can be used, for example, to initialize and free private data.
5811 * Additional callbacks can either be passed directly with SCIPincludeEventhdlr() to SCIP or via specific
5812 * <b>setter functions</b> after a call of SCIPincludeEventhdlrBasic(), see also @ref EVENT_INTERFACE.
5813 *
5814 * @subsection EVENTCOPY
5815 *
5816 * The EVENTCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
5817 * callback as <code>NULL</code> the user disables the execution of the specified event handler for all copied SCIP
5818 * instances. Note that in most cases the event handler in the copied instance will be initialize by those objects (such
5819 * as constraint handlers or propagators) which need this event handler (see \ref cons_knapsack.h). In these cases the copy
5820 * callback can be ignored. In case of general events, such as a new best solution being found
5821 * (SCIP_EVENTTYPE_BESTSOLFOUND), you might want to implement that callback. The event handler example which you find
5822 * in the directory "examples/Eventhdlr/" uses that callback.
5823 *
5824 * @refsnippet{src/scip/event_softtimelimit.c,SnippetEventCopySofttimelimit}
5825 *
5826 * @subsection EVENTFREE
5827 *
5828 * If you are using event handler data, you have to implement this method in order to free the event handler data.
5829 * This can be done by the following procedure:
5830 *
5831 * @refsnippet{src/scip/event_softtimelimit.c,SnippetEventFreeSofttimelimit}
5832 *
5833 * If you have allocated memory for fields in your event handler data, remember to free this memory
5834 * before freeing the event handler data itself.
5835 * If you are using the C++ wrapper class, this method is not available.
5836 * Instead, just use the destructor of your class to free the member variables of your class.
5837 *
5838 *
5839 * @subsection EVENTINIT
5840 *
5841 * The EVENTINIT callback is executed after the problem is transformed.
5842 * The event handler may, e.g., use this call to initialize its event handler data.
5843 *
5844 * @subsection EVENTEXIT
5845 *
5846 * The EVENTEXIT callback is executed before the transformed problem is freed.
5847 * In this method, the event handler should free all resources that have been allocated for the solving process in
5848 * \ref EVENTINIT.
5849 *
5850 * @subsection EVENTINITSOL
5851 *
5852 * The EVENTINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
5853 * begin. The event handler may use this call to initialize its branch-and-bound specific data.
5854 *
5855 * @subsection EVENTEXITSOL
5856 *
5857 * The EVENTEXITSOL callback is executed before the branch-and-bound process is freed. The event handler should use this
5858 * call to clean up its branch-and-bound specific data.
5859 *
5860 * @section EVENTUSAGE Catching and Dropping Events
5861 *
5862 * After you have implemented the event handler, you have to tell SCIP for which events this event handler should be
5863 * used. This can be a general events, such as <code>SCIP_EVENTTYPE_BESTSOLFOUND</code>, or a variable event which is the most common
5864 * way.
5865 *
5866 * In case of a general (not variable) event you use the function SCIPcatchEvent() to attach to an event and
5867 * SCIPdropEvent() to release this event later.
5868 *
5869 * \code
5870 * SCIP_CALL( SCIPcatchEvent( scip, SCIP_EVENTTYPE_BESTSOLFOUND, eventhdlr, NULL, NULL) );
5871 * \endcode
5872 *
5873 * \code
5874 * SCIP_CALL( SCIPdropEvent( scip, SCIP_EVENTTYPE_BESTSOLFOUND, eventhdlr, NULL, NULL) );
5875 * \endcode
5876 *
5877 * If you want trigger some variable event, you use the method SCIPcatchVarEvent() to attach the variable event and
5878 * SCIPdropVarEvent() to drop it later.
5879 *
5880 * \code
5881 * SCIP_CALL( SCIPcatchVarEvent( scip, var, SCIP_EVENTTYPE_VARFIXED, eventhdlr, NULL, NULL) );
5882 * \endcode
5883 *
5884 * \code
5885 * SCIP_CALL( SCIPdropVarEvent( scip, var, SCIP_EVENTTYPE_VARFIXED, eventhdlr, NULL, NULL) );
5886 * \endcode
5887 *
5888 * @section EVENTTYPES Event types
5889 *
5890 * All available events are listed in type_event.h. There are atomic events such as <code>SCIP_EVENTTYPE_VARFIXED</code>
5891 * and combined events such as <code>SCIP_EVENTTYPE_VARCHANGED</code>. The events are encoded via bit masks. Each atomic
5892 * event has a unique power of two. This enables combination of the atomic events.
5893 *
5894 * SCIP only throws atomic events. However, an event handler might be interested in bunch of events. Through the
5895 * underlying bit masks it is possible to combine the atomic events. For example, <code>SCIP_EVENTTYPE_VARCHANGED</code>
5896 * is an event which combines the events <code>SCIP_EVENTTYPE_VARFIXED</code>, <code>SCIP_EVENTTYPE_VARUNLOCKED</code>,
5897 * <code>SCIP_EVENTTYPE_OBJCHANGED</code>, <code>SCIP_EVENTTYPE_GBDCHANGED</code>,
5898 * <code>SCIP_EVENTTYPE_DOMCHANGED</code>, and <code>SCIP_EVENTTYPE_IMPLADDED</code>.
5899 *
5900 * \code
5901 * #define SCIP_EVENTTYPE_VARCHANGED (SCIP_EVENTTYPE_VARFIXED | SCIP_EVENTTYPE_VARUNLOCKED | SCIP_EVENTTYPE_OBJCHANGED
5902 * | SCIP_EVENTTYPE_GBDCHANGED | SCIP_EVENTTYPE_DOMCHANGED | SCIP_EVENTTYPE_IMPLADDED)
5903 * \endcode
5904 *
5905 * Depending on the event type, the event offers different information. The methods which can be used to gain
5906 * access to this information are given in pub_event.h.
5907 *
5908 */
5909
5910/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5911
5912/**@page NLPI How to add interfaces to nonlinear programming solvers
5913 *
5914 * NLPIs are used to interface a solver for nonlinear programs (NLP).
5915 * It is used, e.g., to solve convex relaxations of the problem or to find locally optimal solutions of
5916 * nonlinear relaxations or subproblems.
5917 * The NLPI has been designed such that it can be used independently of a SCIP problem.
5918 *
5919 * While the NLPI itself corresponds to the solver interface, the NLPIPROBLEM corresponds to the
5920 * (solver specific) representation of a concrete nonlinear program.
5921 * An NLP is specified as a set of indexed variables with variable bounds, an objective function,
5922 * and a set of constraints, where each constraint is specified as a function which is restricted to lie
5923 * between given left and right hand sides (possibly infinite).
5924 * A function consists of a linear and a nonlinear part.
5925 * The linear part is specified via variable indices and coefficients, while the nonlinear part is specified via an expression.
5926 * That is, the user of the NLPI does not provide function evaluation callbacks but an algebraic representation of the NLP.
5927 * Interfaces for solvers that require function evaluations can make use of the \ref NLPIOracle "NLPIORACLE", which
5928 * provides functionality to store a NLP and compute functions values, gradients, Jacobians, and Hessians.
5929 * See the interface to Ipopt for an example on how to use the NLPIORACLE.
5930 *
5931 * A complete list of all NLPIs contained in this release can be found \ref NLPIS "here".
5932 *
5933 * We now explain how users can add their own NLP solver interface.
5934 * Take the interface to Ipopt (src/scip/nlpi_ipopt.cpp) as an example.
5935 * Unlike most other plugins, it is written in C++.
5936 * Additional documentation for the callback methods of an NLPI, in particular for their input parameters,
5937 * can be found in the file \ref type_nlpi.h.
5938 *
5939 * Here is what you have to do to implement an NLPI:
5940 * -# 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".
5941 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5942 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5943 * -# Use `SCIPincludeNlpSolverMysolver()` in order to include the NLPI into your SCIP instance,
5944 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5945 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5946 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mysolver".
5947 * -# Adjust the properties of the nlpi (see \ref NLPI_PROPERTIES).
5948 * -# Define the NLPI and NLPIPROBLEM data (see \ref NLPI_DATA).
5949 * -# Implement the interface methods (see \ref NLPI_INTERFACE).
5950 * -# Implement the fundamental callback methods (see \ref NLPI_FUNDAMENTALCALLBACKS).
5951 * -# Implement the additional callback methods (see \ref NLPI_ADDITIONALCALLBACKS). This is optional.
5952 *
5953 *
5954 * @section NLPI_PROPERTIES Properties of an NLPI
5955 *
5956 * At the top of the new file "nlpi_mysolver.c", you can find the NLPI properties.
5957 * These are given as compiler defines.
5958 * The properties you have to set have the following meaning:
5959 *
5960 * \par NLPI_NAME: the name of the NLP solver interface.
5961 * This name is used in the interactive shell to address the NLPI.
5962 * Additionally, if you are searching for an NLPI with SCIPfindNlpi(), this name is looked up.
5963 * Names have to be unique: no two NLPIs may have the same name.
5964 *
5965 * \par NLPI_DESC: the description of the NLPI.
5966 * This string is printed as a description of the NLPI in the interactive shell.
5967 *
5968 * \par NLPI_PRIORITY: the priority of the NLPI.
5969 * If an NLP has to be solved, an NLP solver has to be selected.
5970 * By default, the solver with the NLPI with highest priority is selected.
5971 * The priority of an NLPI should be set according to performance of the solver:
5972 * solvers that provide fast algorithms that are usually successful on a wide range of problems should have a high priority.
5973 * An easy way to list the priorities of all NLPIs is to type "display nlpis" in the interactive shell of SCIP.
5974 *
5975 * @section NLPI_DATA NLPI Data
5976 *
5977 * Below the header "Data structures" you can find structs which are called `struct SCIP_NlpiData` and `struct SCIP_NlpiProblem`.
5978 * In these data structures, you can store the data of your solver interface and of a specific NLP problem.
5979 * For example, you could store a pointer to your NLP solver environment object in the `SCIP_NlpiData` data structure
5980 * and store a pointer to an NLPIORACLE in the `SCIP_NlpiProblem` data structure.
5981 *
5982 * @section NLPI_INTERFACE Interface Methods
5983 *
5984 * At the bottom of "nlpi_mysolver.c", you can find the interface method SCIPincludeNlpSolverXyz(),
5985 * which also appears in "nlpi_mysolver.h".
5986 *
5987 * This method only has to be adjusted slightly.
5988 * It is responsible for creating an NLPI that contains all properties and callback methods of your
5989 * solver interface and included it into SCIP by calling the method SCIPincludeNlpi().
5990 * SCIPincludeNlpSolverXyz() is called by the user (e.g., SCIP), if (s)he wants to use this solver interface in his/her application.
5991 *
5992 * If you are using NLPI data, you have to allocate the memory for the data at this point.
5993 * You can do this by calling:
5994 * \code
5995 * SCIP_CALL( SCIPallocBlockMemory(scip, &nlpidata) );
5996 * \endcode
5997 * You also have to initialize the fields in struct SCIP_NlpiData afterwards. For freeing the
5998 * NLPI data, see \ref NLPIFREE.
5999 *
6000 *
6001 * @section NLPI_FUNDAMENTALCALLBACKS Fundamental Callback Methods of an NLPI
6002 *
6003 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
6004 * an operational algorithm. Most NLPI callbacks are fundamental.
6005 *
6006 * Additional documentation of the callback methods, in particular to their input parameters,
6007 * can be found in \ref type_nlpi.h.
6008 *
6009 * @subsection NLPIFREE
6010 *
6011 * The NLPIFREE callback is executed if the NLP solver interface data structure should be freed, e.g., when a SCIP instance is freed.
6012 *
6013 * @subsection NLPICREATEPROBLEM
6014 *
6015 * The NLPICREATEPROBLEM callback is executed if a particular NLP problem is to be created.
6016 * The callback method should initialize a SCIP_NlpiProblem struct here that corresponds to an empty NLP.
6017 *
6018 * @subsection NLPIFREEPROBLEM
6019 *
6020 * The NLPIFREEPROBLEMPOINTER callback is executed if a particular NLP problem is to be freed.
6021 * The callback method should free a SCIP_NlpiProblem struct here.
6022 *
6023 * @subsection NLPIADDVARS
6024 *
6025 * The NLPIADDVARS callback is executed if a set of variables with lower and upper bounds and names should be added to a particular NLP.
6026 * The callback method must add the new variables behind the previously added variables, if any.
6027 * If NULL is given for the lower bounds arguments, -infinity is assumed as lower bound for each new variable.
6028 * If NULL is given for the upper bounds arguments, +infinity is assumed as upper bound for each new variable.
6029 * It is also permitted to use NULL for the names argument.
6030 *
6031 * @subsection NLPIADDCONSTRAINTS
6032 *
6033 * The NLPIADDCONSTRAINTS callback is executed if a set of constraints should be added to a particular NLP.
6034 * Constraints are specified by providing left- and right-hand-sides, linear coefficients, expressions, and constraint names.
6035 * All of these arguments are optional, giving NULL for left-hand-sides corresponds to -infinity, giving NULL for right-hand-sides corresponds to +infinity.
6036 *
6037 * @subsection NLPISETOBJECTIVE
6038 *
6039 * The NLPISETOBJECTIVE callback is executed to set the objective function of a particular NLP.
6040 *
6041 * @subsection NLPICHGVARBOUNDS
6042 *
6043 * The NLPICHGVARBOUNDS callback is executed to change the bounds on a set of variables of an NLP.
6044 *
6045 * @subsection NLPICHGCONSSIDES
6046 *
6047 * The NLPICHGCONSSIDES callback is executed to change the sides on a set of constraints of an NLP.
6048 *
6049 * @subsection NLPIDELVARSET
6050 *
6051 * The NLPIDELVARSET callback is executed to delete a set of variables from an NLP.
6052 * The caller provides an array in which for each variable it is marked whether it should be deleted.
6053 * In the same array, the method should return the new position of each variable in the NLP, or -1 if it was deleted.
6054 *
6055 * @subsection NLPIDELCONSSET
6056 *
6057 * The NLPIDELCONSSET callback is executed to delete a set of constraints from an NLP.
6058 * The caller provides an array in which for each constraint it is marked whether it should be deleted.
6059 * In the same array, the method should return the new position of each constraint in the NLP, or -1 if it was deleted.
6060 *
6061 * @subsection NLPICHGLINEARCOEFS
6062 *
6063 * The NLPICHGLINEARCOEFS callback is executed to change the coefficients in the linear part of the objective function or a constraint of an NLP.
6064 *
6065 * @subsection NLPICHGEXPR
6066 *
6067 * The NLPICHGEXPR callback is executed to replace the expression of the objective function or a constraint of an NLP.
6068 *
6069 * @subsection NLPICHGOBJCONSTANT
6070 *
6071 * The NLPICHGOBJCONSTANT callback is executed to change the constant offset of the objective function of an NLP.
6072 *
6073 * @subsection NLPISOLVE
6074 *
6075 * The NLPISOLVE callback is executed when an NLP should be solved.
6076 * The solver may use the initial guess provided by \ref NLPISETINITIALGUESS as starting point.
6077 * The status of the solving process and solution can be requested by
6078 * \ref NLPIGETSOLSTAT, \ref NLPIGETTERMSTAT, \ref NLPIGETSOLUTION, and \ref NLPIGETSTATISTICS.
6079 *
6080 * @subsection NLPIGETSOLSTAT
6081 *
6082 * The NLPIGETSOLSTAT callback can be used to request the solution status (solved, infeasible, ...) after an NLP has been solved.
6083 *
6084 * @subsection NLPIGETTERMSTAT
6085 *
6086 * The NLPIGETTERMSTAT callback can be used to request the termination reason (normal, iteration limit, ...) after an NLP has been solved.
6087 *
6088 * @subsection NLPIGETSOLUTION
6089 *
6090 * The NLPIGETSOLUTION callback can be used to request the primal and dual solution values after an NLP solve.
6091 * The method should pass pointers to arrays of variable values to the caller.
6092 * 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.
6093 *
6094 * @subsection NLPIGETSTATISTICS
6095 *
6096 * The NLPIGETSTATISTICS callback can be used to request the statistical values (number of iterations, time, ...) after an NLP solve.
6097 * The method should fill the provided NLPSTATISTICS data structure.
6098 *
6099 * @section NLPI_ADDITIONALCALLBACKS Additional Callback Methods of an NLPI
6100 *
6101 * The additional callback methods do not need to be implemented in every case.
6102 *
6103 * @subsection NLPICOPY
6104 *
6105 * The NLPICOPY callback is executed if the plugin should be copied, e.g., when a SCIP instance is copied.
6106 *
6107 * It is advisable to implement this callback to make the NLP solver available in sub-SCIPs.
6108 * Note that the sub-NLP heuristic solves NLPs in a sub-SCIP.
6109 *
6110 * @subsection NLPIGETSOLVERPOINTER
6111 *
6112 * The NLPIGETSOLVERPOINTER callback can be used to pass a pointer to a solver specific data structure to the user.
6113 * Return NULL if you do not have a pointer to return.
6114 *
6115 * @subsection NLPIGETPROBLEMPOINTER
6116 *
6117 * The NLPIGETPROBLEMPOINTER callback can be used to pass a pointer to a solver specific data structure of the NLP to the user.
6118 *
6119 * @subsection NLPISETINITIALGUESS
6120 *
6121 * The NLPISETINITIALGUESS callback is executed to provide primal and dual initial values for the variables and constraints of an NLP.
6122 * 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.
6123 * 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).
6124 * In this case, the solver should clear previously set starting values and setup its own starting point.
6125 *
6126 */
6127
6128/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6129
6130/**@page EXPRINT How to add interfaces to expression interpreters
6131 *
6132 * An expression interpreter is a tool to compute point-wise the function values, gradients, and
6133 * Hessians of algebraic expressions which are given in the form of an expression.
6134 * Typically, this is done via automatic differentiation.
6135 * It is used, e.g., by an NLP solver interface to compute Jacobians and Hessians for the solver.
6136 *
6137 * The expression interpreter interface in SCIP has been implemented similar to those of the LP solver interface (LPI).
6138 * For one binary, exactly one expression interpreter has to be linked.
6139 * The expression interpreter API has been designed such that it can be used independently from a SCIP problem.
6140 *
6141 * A complete list of all expression interpreters contained in this release can be found \ref EXPRINTS "here".
6142 *
6143 * We now explain how users can add their own expression interpreters.
6144 * Take the interface to CppAD (\ref exprinterpret_cppad.cpp) as an example.
6145 * Unlike most other plugins, it is written in C++.
6146 *
6147 * Additional documentation for the callback methods of an expression interpreter, in particular for their input parameters,
6148 * can be found in the file \ref exprinterpret.h.
6149 *
6150 * Here is what you have to do to implement an expression interpreter:
6151 * -# Copy the file \ref exprinterpret_none.c into a file named "exprinterpret_myad.c".
6152 * Make sure to adjust your build system such that this file is compiled and linked to your project instead of exprinterpret implementations. \n
6153 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6154 * -# Open the new file with a text editor.
6155 * -# Define the expression interpreter data (see \ref EXPRINT_DATA).
6156 * -# Implement the interface methods (see \ref EXPRINT_INTERFACE).
6157 *
6158 *
6159 * @section EXPRINT_DATA Expression Interpreter Data
6160 *
6161 * In `struct SCIP_ExprInt`, you can store the general data of your expression interpreter.
6162 * For example, you could store the environment of your automatic differentiation code.
6163 *
6164 * @section EXPRINT_INTERFACE Interface Methods
6165 *
6166 * The expression interpreter has to implement a set of interface method.
6167 * In your "exprinterpret_myad.c", these methods are mostly dummy methods that return error codes.
6168 *
6169 * @subsection SCIPexprintGetName
6170 *
6171 * The SCIPexprintGetName() method should return the name of the expression interpreter.
6172 *
6173 * @subsection SCIPexprintGetDesc
6174 *
6175 * The SCIPexprintGetDesc() method should return a short description of the expression interpreter, e.g., the name of the developer of the code.
6176 *
6177 * @subsection SCIPexprintGetCapability
6178 *
6179 * The SCIPexprintGetCapability() method should return a bitmask that indicates the capabilities of the expression interpreter,
6180 * i.e., whether it can compute gradients and Hessians.
6181 *
6182 * @subsection SCIPexprintCreate
6183 *
6184 * The SCIPexprintCreate() method is called to create an expression interpreter data structure.
6185 * The method should initialize a `struct SCIP_ExprInt` here.
6186 *
6187 * @subsection SCIPexprintFree
6188 *
6189 * The SCIPexprintFree() method is called to free an expression interpreter data structure.
6190 * The method should free a `struct SCIP_ExprInt` here.
6191 *
6192 * @subsection SCIPexprintCompile
6193 *
6194 * The SCIPexprintCompile() method is called to initialize the data structures that are required to evaluate a particular expression.
6195 * The expression interpreter can create and return data that is particular to a given expression in the argument `exprintdata`.
6196 *
6197 * @subsection SCIPexprintFreeData
6198 *
6199 * The SCIPexprintFreeData() method is called to free the data that is particular to a given expression and was possibly created in SCIPexprintCompile().
6200 *
6201 * @subsection SCIPexprintGetExprCapability
6202 *
6203 * The SCIPexprintGetExprCapability() method is called to request the capability to evaluate a specific expression by the expression interpreter.
6204 *
6205 * In cases of user-given expressions, higher order derivatives may not be available for the user-expression,
6206 * even if the expression interpreter could handle these. This method allows to recognize that, e.g., the
6207 * Hessian for an expression is not available because it contains a user expression that does not provide
6208 * Hessians.
6209 *
6210 * @subsection SCIPexprintEval
6211 *
6212 * The SCIPexprintEval() method is called when the value of an expression should be computed for a point.
6213 *
6214 * @subsection SCIPexprintGrad
6215 *
6216 * The SCIPexprintGrad() method is called when the gradient of an expression represented by an expression should be computed for a point.
6217 *
6218 * @subsection SCIPexprintHessianSparsity
6219 *
6220 * The SCIPexprintHessianSparsity() method is called when the sparsity structure of the Hessian matrix should be computed and returned.
6221 * Only the position of nonzero entries in the lower-triangular part of Hessian should be reported.
6222 *
6223 * @subsection SCIPexprintHessian
6224 *
6225 * The SCIPexprintHessian() method is called when the Hessian of an expression should be computed for a point.
6226 */
6227
6228/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6229
6230/**@page TABLE How to add statistics tables
6231 *
6232 * After solving a constraint integer program, SCIP can display statistics tables with information about, e.g., the solving time,
6233 * number of nodes, LP iterations or the number of calls and successes of different plugins via "display statistics" in the shell
6234 * or via SCIPprintStatistics() in the C-interface. There already exists a wide variety of statistics tables which can be activated
6235 * or deactivated on demand, see src/scip/table_default.c. Additionally, the user can implement his/her own statistics tables
6236 * in order to display problem or algorithm specific values.
6237 * \n
6238 * A complete list of all statistics tables contained in this release can be found \ref TABLES "here".
6239 *
6240 * We now explain how users can add their own statistics tables.
6241 * We give the explanation for creating your own source file for each additional statistics table. Of course, you can collect
6242 * different additional statistics tables in one source file.
6243 * Take src/scip/table_default.c, where all default statistics tables are collected, as an example.
6244 * As all other default plugins, the default statistics table plugins and the statistics table template are written in C.
6245 * C++ users can easily adapt the code by using the scip::ObjTable wrapper base class and implement the scip_...() virtual methods
6246 * instead of the SCIP_DECL_TABLE... callback methods.
6247 *
6248 *
6249 * Additional documentation for the callback methods of a statistics table can be found in the file type_table.h.
6250 *
6251 * Here is what you have to do to implement a statistics table (assuming your statistics table is named "mystatisticstable"):
6252 * -# Copy the template files src/scip/table_xyz.c and src/scip/table_xyz.h into files named "table_mystatisticstable.c"
6253 * and "table_mystatisticstable.h".
6254 * \n
6255 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
6256 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6257 * -# Use SCIPincludeTableMystatisticstable() in order to include the statistics table into your SCIP instance,
6258 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
6259 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
6260 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mystatisticstable".
6261 * -# Adjust the \ref TABLE_PROPERTIES "properties of the statistics table".
6262 * -# Define the \ref TABLE_DATA "statistics table data". This is optional.
6263 * -# Implement the \ref TABLE_INTERFACE "interface methods".
6264 * -# Implement the \ref TABLE_FUNDAMENTALCALLBACKS "fundamental callback methods".
6265 * -# Implement the \ref TABLE_ADDITIONALCALLBACKS "additional callback methods". This is optional.
6266 *
6267 *
6268 * @section TABLE_PROPERTIES Properties of a Statistics Table
6269 *
6270 * At the top of the new file "table_mystatisticstable.c" you can find the statistics table properties.
6271 * These are given as compiler defines.
6272 * In the C++ wrapper class, you have to provide the statistics table properties by calling the constructor
6273 * of the abstract base class scip::ObjTable from within your constructor.
6274 * The properties you have to set have the following meaning:
6275 *
6276 * \par TABLE_NAME: the name of the statistics table.
6277 * This name is used in the interactive shell to address the statistics table.
6278 * Additionally, if you are searching for a statistics table with SCIPfindTable(), this name is looked up.
6279 * Names have to be unique: no two statistic tables may have the same name.
6280 *
6281 * \par TABLE_DESC: the description of the statistics table.
6282 * This string is printed as a description of the statistics table in the interactive shell.
6283 *
6284 * \par TABLE_POSITION: the position of the statistics table.
6285 * In the statistics output, the statistics tables will be ordered by increasing position. Compare with the
6286 * default statistics tables in "table_default.c" to find a value which will give you the desired position
6287 * between the default statistics tables. If you give your table a negative position value, it will appear
6288 * before all SCIP statistcs, with a value larger than 20000 it will appear after all default statistics.
6289 *
6290 * \par TABLE_EARLIEST_STAGE: output of the statistics table is only printed from this stage onwards
6291 * The output routine of your statistics table will only be called if SCIP has reached this stage. For
6292 * example, the default table "tree" will only output information starting from SCIP_STAGE_SOLVING, because
6293 * there is no meaningful information available before, while the "presolver" table can already be called
6294 * in SCIP_STAGE_TRANSFORMED.
6295 *
6296 * @section TABLE_DATA Statistics Table Data
6297 *
6298 * Below the header "Data structures" you can find a struct which is called "struct SCIP_TableData".
6299 * In this data structure, you can store the data of your statistics table. For example, you should store the adjustable
6300 * parameters of the statistics table in this data structure.
6301 * If you are using C++, you can add statistics table data as usual as object variables to your class.
6302 * \n
6303 * Defining statistics table data is optional. You can leave the struct empty.
6304 *
6305 *
6306 * @section TABLE_INTERFACE Interface Methods
6307 *
6308 * At the bottom of "table_mystatisticstable.c" you can find the interface method SCIPincludeTableMystatisticstable(), which also
6309 * appears in "table_mystatisticstable.h".
6310 * \n
6311 * This method only has to be adjusted slightly.
6312 * It is responsible for notifying SCIP of the presence of the statistics table by calling the method
6313 * SCIPincludeTable().
6314 *
6315 * 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
6316 * application.
6317 *
6318 * If you are using statistics table data, you have to allocate the memory for the data at this point.
6319 * You can do this by calling:
6320 * \code
6321 * SCIP_CALL( SCIPallocBlockMemory(scip, &tabledata) );
6322 * \endcode
6323 * You also have to initialize the fields in struct SCIP_TableData afterwards.
6324 *
6325 * Although this is very uncommon, you may also add user parameters for your statistics table, see the method
6326 * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
6327 *
6328 *
6329 * @section TABLE_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Statistics Table
6330 *
6331 * Statistics table plugins have only one fundamental callback method, namely the \ref TABLEOUTPUT method.
6332 * This method has to be implemented for every display column; the other callback methods are optional.
6333 * In the C++ wrapper class scip::ObjTable, the scip_output() method (which corresponds to the \ref TABLEOUTPUT callback) is a virtual
6334 * abstract member function.
6335 * You have to implement it in order to be able to construct an object of your statistics table class.
6336 *
6337 * Additional documentation for the callback methods can be found in type_table.h.
6338 *
6339 * @subsection TABLEOUTPUT
6340 *
6341 * The TABLEOUTPUT callback is called whenever SCIP is asked to print statistics (because the user typed "display statistics"
6342 * in the shell or called SCIPprintStatistics()). In this callback, the table should print all of its information to the given file
6343 * (which may be NULL if the output should be printed to the console).
6344 *
6345 * Typical methods called by a statistics table are, for example, SCIPdispLongint(), SCIPdispInt(), SCIPdispTime(), and
6346 * SCIPinfoMessage().
6347 *
6348 *
6349 * @section TABLE_ADDITIONALCALLBACKS Additional Callback Methods of a Statistics Table
6350 *
6351 * The additional callback methods do not need to be implemented in every case.
6352 * They can be used, for example, to initialize and free private data.
6353 *
6354 * @subsection TABLECOPY
6355 *
6356 * The TABLECOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this callback
6357 * as <code>NULL</code> the user disables the execution of the specified column. In general it is probably not needed to
6358 * implement that callback since the output of the copied instance is usually suppressed. In the other case or for
6359 * debugging the callback should be implement.
6360 *
6361 *
6362 * @subsection TABLEFREE
6363 *
6364 * If you are using statistics table data, you have to implement this method in order to free the statistics table data.
6365 * This can be done by the following procedure:
6366 * @refsnippet{tests/src/misc/snippets.c,SnippetTableFree}
6367 *
6368 * If you have allocated memory for fields in your statistics table data, remember to free this memory
6369 * before freeing the statistics table data itself.
6370 * If you are using the C++ wrapper class, this method is not available.
6371 * Instead, just use the destructor of your class to free the member variables of your class.
6372 *
6373 * @subsection TABLEINIT
6374 *
6375 * The TABLEINIT callback is executed after the problem is transformed.
6376 * The statistics table may, e.g., use this call to initialize its statistics table data.
6377 *
6378 * @subsection TABLEEXIT
6379 *
6380 * The TABLEEXIT callback is executed before the transformed problem is freed.
6381 * In this method, the statistics table should free all resources that have been allocated for the solving process in
6382 * \ref TABLEINIT.
6383 *
6384 * @subsection TABLEINITSOL
6385 *
6386 * The TABLEINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
6387 * begin. The statistics table may use this call to initialize its branch-and-bound specific data.
6388 *
6389 * @subsection TABLEEXITSOL
6390 *
6391 * The TABLEEXITSOL callback is executed before the branch-and-bound process is freed. The statistics table should use this
6392 * call to clean up its branch-and-bound specific data.
6393 */
6394
6395/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6396
6397/**@page BENDER How to add custom Benders' decomposition implementations
6398 *
6399 * Benders' decomposition is a very popular mathematical programming technique that is applied to solve structured
6400 * problems. Problems that display a block diagonal structure are particularly amenable to the application of Benders'
6401 * decomposition. Such problems are given by
6402 *
6403 * \f[
6404 * \begin{array}[t]{rllclcl}
6405 * \min & \displaystyle & c^{T}x & + & d^{T}y \\
6406 * & \\
6407 * subject \ to & \displaystyle & Ax & & & = & b \\
6408 * & \\
6409 * & \displaystyle & Tx & + & Hy & = & h \\
6410 * & \\
6411 * & & x & & & \in & \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
6412 * & & & & y & \in & \mathbb{R}^{m} \\
6413 * \end{array}
6414 * \f]
6415 *
6416 * The variables \f$x\f$ and \f$y\f$ are described as the first and second stage variables respectively. In the
6417 * classical use of Benders' decomposition, it is a requirement that the all second stage variables are continuous.
6418 * Extensions to the classical Benders' decomposition approach have permitted the use of more general second stage
6419 * problems.
6420 *
6421 * The application of Benders' decomposition to the above problem results in a subproblem, given by
6422 *
6423 * \f[
6424 * \begin{array}[t]{rll}
6425 * \min & \displaystyle & d^{T}y \\
6426 * & \\
6427 * subject \ to & \displaystyle & Hy = h - T\bar{x} \\
6428 * & \\
6429 * & & y \in \mathbb{R}^{m} \\
6430 * \end{array}
6431 * \f]
6432 *
6433 * where \f$\bar{x}\f$ is a solution vector of the first stage variables. As such, the subproblem is a problem only in
6434 * \f$y\f$. The dual solution to the subproblem, either an extreme point or extreme ray, is used to generate cuts that
6435 * are added to the master problem. Let \f$\lambda\f$ be the vector of dual variables associated with the set of
6436 * constraints from the subproblem. If, for a given \f$\bar{x}\f$, the subproblem is infeasible, then \f$\lambda\f$
6437 * corresponds to a dual ray and is used to produce the cut
6438 *
6439 * \f[
6440 * 0 \geq \lambda(h - Tx)
6441 * \f]
6442 *
6443 * which eliminates \f$\bar{x}\f$ from the master problem. If, for a given \f$\bar{x}\f$, the subproblem is feasible,
6444 * then \f$\lambda\f$ corresponds to a dual extreme point and is used to produce the cut
6445 *
6446 * \f[
6447 * \varphi \geq \lambda(h - Tx)
6448 * \f]
6449 *
6450 * where \f$\varphi\f$ is an auxiliary variable added to the master problem as an underestimator of the optimal
6451 * subproblem objective function value.
6452 *
6453 * Given \f$\Omega^{p}\f$ and \f$\Omega^{r}\f$ as the sets of dual extreme points and rays of the subproblem,
6454 * respectively, the Benders' decomposition master problem is given by
6455 *
6456 * \f[
6457 * \begin{array}[t]{rll}
6458 * \min & \displaystyle & c^{T}x + \varphi \\
6459 * & \\
6460 * subject \ to & \displaystyle & Ax = b \\
6461 * & \\
6462 * & \displaystyle & \varphi \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r}\\
6463 * & \\
6464 * & \displaystyle & 0 \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r} \\
6465 * & \\
6466 * & & x \in \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
6467 * & & \varphi \in \mathbb{R} \\
6468 * \end{array}
6469 * \f]
6470 *
6471 * The Benders' decomposition framework of SCIP allows the user to provide a custom implementation of many aspects of
6472 * the Benders' decomposition algorithm. It is possible to implement multiple Benders' decompositions that work in
6473 * conjunction with each other. Such a situation is where you may have different formulations of the Benders'
6474 * decomposition subproblem.
6475 *
6476 * The current list of all Benders' decomposition implementations available in this release can be found \ref BENDERS
6477 * "here".
6478 *
6479 * We now explain how users can add their own Benders' decomposition implementations.
6480 * Take the default Benders' decomposition implementation (src/scip/benders_default.c) as an example. Same as all other
6481 * default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjBenders wrapper base
6482 * class and implement the scip_...() virtual methods instead of the SCIP_DECL_BENDERS... callback methods.
6483 *
6484 * Additional documentation for the callback methods of a Benders' decomposition implementation, in particular for the
6485 * input parameters, can be found in the file type_benders.h.
6486 *
6487 * Here is what you have to do to implement a custom Benders' decomposition:
6488 * -# Copy the template files src/scip/benders_xyz.c and src/scip/benders_xyz.h into files "benders_mybenders.c" and
6489 * "benders_mybenders.h".
6490 \n
6491 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
6492 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6493 * -# Use SCIPincludeBendersMybenders() in order to include the Benders' decomposition into your SCIP instance, e.g., in
6494 * the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
6495 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
6496 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mybenders".
6497 * -# Adjust the properties of the Benders' decomposition (see \ref BENDERS_PROPERTIES).
6498 * -# Define the Benders' decomposition data (see \ref BENDERS_DATA). This is optional.
6499 * -# Implement the interface methods (see \ref BENDERS_INTERFACE).
6500 * -# Implement the fundamental callback methods (see \ref BENDERS_FUNDAMENTALCALLBACKS).
6501 * -# Implement the additional callback methods (see \ref BENDERS_ADDITIONALCALLBACKS). This is optional.
6502 *
6503 *
6504 * @section BENDERS_PROPERTIES Properties of a Benders' decomposition
6505 *
6506 * At the top of the new file "benders_mybenders.c", you can find the Benders' decomposition properties.
6507 * These are given as compiler defines.
6508 * In the C++ wrapper class, you have to provide the Benders' decomposition properties by calling the constructor
6509 * of the abstract base class scip::ObjBenders from within your constructor.
6510 * The properties you have to set have the following meaning:
6511 *
6512 * \par BENDERS_NAME: the name of the Benders' decomposition.
6513 * This name is used in the interactive shell to address the Benders' decomposition.
6514 * Additionally, if you are searching for a Benders' decomposition with SCIPfindBenders(), this name is looked up.
6515 * Names have to be unique: no two Benders' decompositions may have the same name.
6516 *
6517 * \par BENDERS_DESC: the description of the Benders' decomposition.
6518 * This string is printed as a description of the Benders' decomposition in the interactive shell.
6519 *
6520 * \par BENDERS_PRIORITY: the priority of the Benders' decomposition.
6521 * During the enforcement and checking of solutions in src/scip/cons_benders.c and src/scip/cons_benderslp.c, every
6522 * active Benders' decompositions are called. The execution method of the Benders' decomposition calls each of the
6523 * subproblems and generates cuts from their solutions. So the active Benders' decompositions are called in order of
6524 * priority until a cut is generated or feasibility is proven.
6525 * \n
6526 * The priority of the Benders' decomposition should be set according to the difficulty of solving the subproblems and
6527 * the generation of cuts. However, it is possible to prioritise the Benders' decompositions with respect to the
6528 * strength of the subproblem formulation and the resulting cuts.
6529 *
6530 * \par BENDERS_CUTLP: should Benders' decomposition cuts be generated during the enforcement of LP solutions.
6531 * This is a flag that is used by src/scip/cons_benders.c and src/scip/cons_benderslp.c to idicate whether the
6532 * enforcement of LP solutions should involve solving the Benders' decomposition subproblems. This should be set to TRUE
6533 * to have an exact solution algorithm. In the presence of multiple Benders' decomposition, it may be desired to enforce
6534 * the LP solutions for only a subset of those implemented.
6535 *
6536 * \par BENDERS_CUTRELAX: should Benders' decomposition cuts be generated during the enforcement of relaxation solutions.
6537 * This is a flag that is used by src/scip/cons_benders.c and src/scip/cons_benderslp.c to idicate whether the
6538 * enforcement of relaxation solutions should involve solving the Benders' decomposition subproblems. This should be
6539 * set to TRUE to have an exact solution algorithm. In the presence of multiple Benders' decomposition, it may be desired
6540 * to enforce the relaxation solutions for only a subset of those implemented. This parameter will only take effect if
6541 * external relaxation have been implemented.
6542 *
6543 * \par BENDERS_CUTPSEUDO: should Benders' decomposition subproblems be solved during the enforcement of pseudo solutions.
6544 * This is a flag that is used by src/scip/cons_benders.c and src/scip/cons_benderslp.c to indicate whether the
6545 * enforcement of pseudo solutions should involve solving the Benders' decomposition subproblems. This should be set to
6546 * TRUE, since not enforcing pseudo solutions could result in an error or suboptimal result. During the enforcement of
6547 * pseudo solutions, no cuts are generated. Only a flag to indicate whether the solution is feasible or if the LP should
6548 * be solved again is returned.
6549 *
6550 * \par BENDERS_SHAREAUXVARS: should this Benders' decomposition use the auxiliary variables from the highest priority
6551 * Benders' decomposition.
6552 * This parameter only takes effect if multiple Benders' decompositions are implemented. Consider the case that two Benders'
6553 * decompositions are implemented with different formulations of the subproblem. Since the subproblems in each of the
6554 * decomposition will have the same optimal solution, then it is useful to only have a single auxiliary variable for the
6555 * two different subproblems. This means that when an optimality cut is generated in the lower priority Benders'
6556 * decomposition, the auxiliary variable from the highest priority Benders' decomposition will be added to the right
6557 * hand side.
6558 *
6559 * @section BENDERS_DATA Benders' decomposition Data
6560 *
6561 * Below the header "Data structures" you can find a struct which is called "struct SCIP_BendersData".
6562 * In this data structure, you can store the data of your Benders' decomposition. For example, you should store the adjustable
6563 * parameters of the Benders' decomposition in this data structure. In a Benders' decomposition, user parameters for the
6564 * number of subproblems and an array to store the subproblem SCIP instances could be useful.
6565 * \n
6566 * Defining Benders' decomposition data is optional. You can leave the struct empty.
6567 *
6568 * @section BENDERS_INTERFACE Interface Methods
6569 *
6570 * At the bottom of "benders_mybenders.c", you can find the interface method SCIPincludeBendersMybenders(),
6571 * which also appears in "benders_mybenders.h"
6572 * SCIPincludeBendersMybenders() is called by the user, if (s)he wants to include the Benders' decomposition,
6573 * i.e., if (s)he wants to use the Benders' decomposition in his/her application.
6574 *
6575 * This method only has to be adjusted slightly.
6576 * It is responsible for notifying SCIP of the presence of the Benders' decomposition. For this, you can either call SCIPincludeBenders(),
6577 * or SCIPincludeBendersBasic() since SCIP version 3.0. In the latter variant, \ref BENDERS_ADDITIONALCALLBACKS "additional callbacks"
6578 * must be added via setter functions as, e.g., SCIPsetBendersCopy(). We recommend this latter variant because
6579 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
6580 * variant must be manually adjusted with every SCIP release containing new callbacks for Benders' decompositions in order to compile.
6581 *
6582 * If you are using Benders' decomposition data, you have to allocate the memory
6583 * for the data at this point. You can do this by calling:
6584 * \code
6585 * SCIP_CALL( SCIPallocBlockMemory(scip, &bendersdata) );
6586 * \endcode
6587 * You also have to initialize the fields in "struct SCIP_BendersData" afterwards. For freeing the
6588 * Benders' decomposition data, see \ref BENDERSFREE.
6589 *
6590 * You may also add user parameters for your Benders' decomposition, see \ref PARAM for how to add user parameters and
6591 * the method SCIPincludeBendersDefault() in src/scip/benders_default.c for an example.
6592 *
6593 * It is advised to disable presolving for the Benders' decomposition master problem by calling SCIPsetPresolving() with
6594 * the parameter SCIP_PARAMSETTING_OFF. Presolving should be disabled because reductions on the master problem could be
6595 * invalid since constraints have been transferred to the subproblems. It is not necessary to disable all presolving,
6596 * but care must be taken when it is used for the Benders' decomposition master problem.
6597 *
6598 * The Benders' decomposition constraint handler, see src/scip/cons_benders.c, includes a presolver for tightening the
6599 * bound on the auxiliary variables. This presolver can be enabled with by setting "presolving/maxround" to 1 and
6600 * "constraints/benders/maxprerounds" to 1. This presolver solves the Benders' decomposition subproblems without fixing
6601 * the master problem variables to find a lower bound for the auxiliary variable.
6602 *
6603 *
6604 * @section BENDERS_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Benders' decomposition
6605 *
6606 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
6607 * an operational algorithm.
6608 * They are passed together with the Benders' decomposition itself to SCIP using SCIPincludeBenders() or SCIPincludeBendersBasic(),
6609 * see @ref BENDERS_INTERFACE.
6610 *
6611 * Benders' decomposition plugins have two callbacks, @ref BENDERSGETVAR and @ref BENDERSCREATESUB that must be implemented.
6612 *
6613 * Additional documentation for the callback methods, in particular to their input parameters,
6614 * can be found in type_benders.h.
6615 *
6616 * @subsection BENDERSGETVAR
6617 *
6618 * The BENDERSGETVAR callback provides a mapping between the master problem variables and their corresponding subproblem
6619 * variables, and vice versa. The parameters of this function include the variable for which the mapped variable is
6620 * desired and the problem number for the mapped variable. When requesting a subproblem variable for a given master
6621 * problem variable, the master variable is input with the appropriate subproblem index. If a master problem variable is
6622 * requested for a given subproblem variable, then the subproblem variable is input with the subproblem index given as
6623 * -1.
6624 *
6625 * An example of how to implement the mapping between the master and subproblem variables is shown by
6626 *
6627 * @refsnippet{src/scip/benders_default.c,SnippetBendersGetvarDefault}
6628 *
6629 * In the above code snippet, the hashmaps providing the mapping between the master and subproblem variables are
6630 * constructed in the <code>SCIP_STAGE_INIT</code> stage (see \ref BENDERSINIT).
6631 *
6632 * The requested variable is returned via the mappedvar parameter. There may not exist a corresponding master
6633 * (subproblem) variable for every input subproblem (master) variable. In such cases were no corresponding variable
6634 * exists, mappedvar must be returned as NULL.
6635 *
6636 * The mapped variables are retrieved by calling SCIPgetBendersMasterVar() and SCIPgetBendersSubproblemVar().
6637 *
6638 * The variable mapping must be created before <code>SCIP_STAGE_PRESOLVE</code> stage. This is because the variable
6639 * mapping is required for checking solutions found by heuristics during presolving.
6640 *
6641 * @subsection BENDERSCREATESUB
6642 *
6643 * The BENDERSCREATESUB callback is executed during the <code>SCIP_STAGE_INIT</code> stage. In this function, the
6644 * user must register the SCIP instances for each subproblem. The BENDERSCREATESUB callback is executed once for each
6645 * subproblem. The user registers a subproblem by calling SCIPbendersAddSubproblem().
6646 *
6647 * It is possible to build the SCIP instance for the subproblem during the execution of this callback. However, it may
6648 * be more convenient to build the subproblem instances during the problem creation stage of the master problem and
6649 * store the subproblem SCIP instances in SCIP_BendersData. This approach is used in src/scip/benders_default.c.
6650 *
6651 * @section BENDERS_ADDITIONALCALLBACKS Additional Callback Methods of a Benders' decomposition implementation
6652 *
6653 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
6654 * implemented for most applications, they can be used, for example, to initialize and free private data.
6655 * Additional callbacks can either be passed directly with SCIPincludeBenders() to SCIP or via specific
6656 * <b>setter functions</b> after a call of SCIPincludeBendersBasic(), see also @ref BENDERS_INTERFACE.
6657 *
6658 * @subsection BENDERSFREE
6659 *
6660 * If you are using Benders' decomposition data (see \ref BENDERS_DATA and \ref BENDERS_INTERFACE), you have to
6661 * implement this method in order to free the Benders' decomposition data. This can be done by the following procedure:
6662 *
6663 * @refsnippet{src/scip/benders_default.c,SnippetBendersFreeDefault}
6664 *
6665 * If you have allocated memory for fields in your Benders' decomposition data, remember to free this memory
6666 * before freeing the Benders' decomposition data itself.
6667 * If you are using the C++ wrapper class, this method is not available.
6668 * Instead, just use the destructor of your class to free the member variables of your class.
6669 *
6670 * @subsection BENDERSCOPY
6671 *
6672 * The BENDERSCOPY callback is executed when a SCIP instance is copied, e.g. to
6673 * solve a sub-SCIP. By
6674 * defining this callback as
6675 * <code>NULL</code> the user disables the execution of the specified
6676 * separator for all copied SCIP instances. This may deteriorate the performance
6677 * of primal heuristics using sub-SCIPs.
6678 *
6679 * If a user wishes to employ the Large Neighbourhood Benders' Search, it is necessary for the BENDERSCOPY callback to
6680 * be implemented. This is required because the sub-SCIP instances of large neighbourhood search heuristics can only
6681 * access the implemented Benders' decomposition if it is copied via the BENDERSCOPY callback.
6682 *
6683 * @subsection BENDERSINIT
6684 *
6685 * The BENDERSINIT callback is executed after the problem is transformed.
6686 * The Benders' decomposition implementation may, e.g., use this call to initialize its Benders' decomposition data. In
6687 * src/scip/benders_default.c BENDERSINIT is used to create the mapping between the master and subproblem variables.
6688 * The difference between the original and the transformed problem is explained in
6689 * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
6690 *
6691 * @subsection BENDERSEXIT
6692 *
6693 * The BENDERSEXIT callback is executed before the transformed problem is freed.
6694 * In this method, the Benders' decomposition implementation should free all resources that have been allocated for
6695 * the solving process in BENDERSINIT.
6696 *
6697 * @subsection BENDERSINITPRE
6698 *
6699 * The BENDERSINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
6700 * The Benders' decomposition may use this call to initialize its presolving data before the presolving process begins.
6701 *
6702 * @subsection BENDERSEXITPRE
6703 *
6704 * The BENDERSEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
6705 * The Benders' decomposition implementation may use this call, e.g., to clean up its presolving data.
6706 * Besides clean up, no time consuming operations should be done.
6707 *
6708 * @subsection BENDERSINITSOL
6709 *
6710 * The BENDERSINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
6711 * begin. The Benders' decomposition implementation may use this call to initialize its branch-and-bound specific data.
6712 *
6713 * @subsection BENDERSEXITSOL
6714 *
6715 * The BENDERSEXITSOL callback is executed before the branch-and-bound process is freed. The Benders' decomposition
6716 * implementation should use this call to clean up its branch-and-bound data.
6717 *
6718 * @subsection BENDERSPRESUBSOLVE
6719 *
6720 * The BENDERSPRESUBSOLVE callback is provided to give the user an opportunity in each iteration to perform any setup
6721 * operations prior to solving the subproblems. This callback also allows the user to skip the subproblem solve for the
6722 * current iteration. In this case, the user must set the result parameter appropriately
6723 * - the subproblem was not solved in this iteration. Other decompositions will be checked (SCIP_DIDNOTRUN).
6724 * - a constraint has been added to the master problem. No other decompositions will be checked (SCIP_CONSADDED).
6725 * - a cut has been added to the master problem. No other decompositions will be checked (SCIP_SEPARATED).
6726 * - feasibility of the solution is reported to SCIP. Other decompositions will be checked (SCIP_FEASIBLE).
6727 * - infeasibility of the solution is reported to SCIP. No other decompositions will be checked (SCIP_INFEASIBLE).
6728 *
6729 * @subsection BENDERSSOLVESUBCONVEX
6730 *
6731 * Two different subproblem solving functions are provide in the Benders' decomposition framework, BENDERSSOLVESUBCONVEX
6732 * and BENDERSSOLVESUB. These two solving functions are used in the two solving loops of the Benders' decomposition
6733 * framework. The first solving loop solves convex subproblems and convex relaxations of CIPs. The BENDERSSOLVESUBCONVEX
6734 * callback is executed only during the FIRST solving loop. Benders' cut generating methods suitable for convex
6735 * subproblems are executed during this solving loop. If a cut is found, then the second solve loop is not executed. If
6736 * your decomposition does not have any convex subproblems, then it is not necessary to implement the
6737 * BENDERSSOLVESUBCONVEX callback. However, it may be computationally beneficial to solve the convex relaxation of CIP
6738 * subproblems, such as the LP relaxation of a MIP subproblem.
6739 *
6740 * The second solve loop expects that the CIP subproblems are solved to optimality.
6741 *
6742 * If you implement the BENDERSSOLVESUBCONVEX callback, it is necessary to implement the BENDERSFREESUB callback.
6743 *
6744 * The objective function value after the subproblem solve and the result must be returned. The permissible results
6745 * are:
6746 * - the subproblem was not solved in this iteration (SCIP_DIDNOTRUN)
6747 * - the subproblem is solved and is feasible (SCIP_FEASIBLE)
6748 * - the subproblem is solved and is infeasible (SCIP_INFEASIBLE)
6749 * - the subproblem is solved and is unbounded (SCIP_UNBOUNDED)
6750 *
6751 * @subsection BENDERSSOLVESUB
6752 *
6753 * The BENDERSSOLVESUB is executed only during the SECOND solve loop. This callback function is used to solve CIP
6754 * subproblems. If your decomposition does not have any CIP subproblems, then it is not necessary to implement the
6755 * BENDERSSOLVESUB callback.
6756 *
6757 * If you implement the BENDERSSOLVESUB callback, it is necessary to implement the BENDERSFREESUB callback.
6758 *
6759 * The objective function value after the subproblem solve and the result must be returned. The permissible results
6760 * are:
6761 * - the subproblem was not solved in this iteration (SCIP_DIDNOTRUN)
6762 * - the subproblem is solved and is feasible (SCIP_FEASIBLE)
6763 * - the subproblem is solved and is infeasible (SCIP_INFEASIBLE)
6764 * - the subproblem is solved and is unbounded (SCIP_UNBOUNDED)
6765 *
6766 * @subsection BENDERSPOSTSOLVE
6767 *
6768 * The BENDERSPOSTSOLVE callback is executed after the subproblems have been solved and any required cuts have been
6769 * generated, but before the subproblems are freed. This callback provides the user an opportunity to interact the
6770 * subproblems at a global level. For example, the user is able to construct a solution to the original problem by
6771 * combining the solutions from the master problem and all subproblems.
6772 *
6773 * Additionally, the user is able to merge subproblems into the master problem during the execution of this callback.
6774 * The merging of subproblems into the master problem could be desired if it is too time consuming to satisfy the
6775 * feasibility of a subproblem or the appropriate cutting methods are not available for the provided subproblem. A list
6776 * of indicies of subproblems suitable for merging are given in the mergecands array. The first npriomergecands are the
6777 * merge candidates that must be merged into the master problem. If they are not, then the solution process will
6778 * terminate with an error. These merge candidates arise if a cut could not be generated due to numerical difficulties.
6779 * The remaining nmergecands - npriomergecands are subproblems that could be merged into the master problem if desired
6780 * by the user.
6781 *
6782 * @subsection BENDERSFREESUB
6783 *
6784 * The BENDERSFREESUB callback is executed to clean up the subproblems after the solving process and prepare them for
6785 * the next iteration. Typically, SCIPfreeTransform() is called for each subproblem to free the transformed problem.
6786 *
6787 */
6788
6789/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6790
6791/**@page BENDERSCUT How to add custom Benders' decomposition cut generation methods
6792 *
6793 * The Benders' decomposition framework of SCIP allows the user to provide a custom implementation of cut generation
6794 * methods. The Benders' decomposition cut methods are linked to the Benders' decomposition implementations, not the
6795 * master problem SCIP instance. As such, you are able to have different Benders' decomposition cut methods for each
6796 * included Benders' decomposition.
6797 * The current list of all Benders' decomposition cut generation methods available in this release can be found
6798 * \ref BENDERSCUTS "here".
6799 *
6800 * We now explain how users can add their own Benders' decomposition cut methods. Take the default Benders'
6801 * decomposition cut method (src/scip/benderscut_opt.c) as an example. This Benders' decomposition cut method generates
6802 * a classical optimality cut from the optimal dual solution to the convex relaxation of the Benders' decomposition
6803 * subproblem. Same as all other default plugins, it is written in C. C++ users can easily adapt the code by using the
6804 * scip::ObjBenderscut wrapper base class and implement the scip_...() virtual methods instead of the
6805 * SCIP_DECL_BENDERSCUT... callback methods.
6806 *
6807 * Additional documentation for the callback methods of a Benders' decomposition cut methods, in particular for the
6808 * input parameters, can be found in the file type_benderscut.h.
6809 *
6810 * Here is what you have to do to implement a custom Benders' decomposition cut method:
6811 * -# Copy the template files src/scip/benderscut_xyz.c and src/scip/benderscut_xyz.h into files "benderscut_mybenderscut.c" and
6812 * "benderscut_mybenderscut.h".
6813 \n
6814 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
6815 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6816 * -# Use SCIPincludeBenderscutMybenderscut() in order to include the Benders' decomposition cut method into your SCIP
6817 * instance, e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
6818 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
6819 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mybenderscut".
6820 * -# Adjust the properties of the Benders' decomposition (see \ref BENDERSCUT_PROPERTIES).
6821 * -# Define the Benders' decomposition data (see \ref BENDERSCUT_DATA). This is optional.
6822 * -# Implement the interface methods (see \ref BENDERSCUT_INTERFACE).
6823 * -# Implement the fundamental callback methods (see \ref BENDERSCUT_FUNDAMENTALCALLBACKS).
6824 * -# Implement the additional callback methods (see \ref BENDERSCUT_ADDITIONALCALLBACKS). This is optional.
6825 *
6826 *
6827 * @section BENDERSCUT_PROPERTIES Properties of a Benders' decomposition
6828 *
6829 * At the top of the new file "benderscut_mybenderscut.c", you can find the Benders' decomposition cut methods
6830 * properties. These are given as compiler defines.
6831 * In the C++ wrapper class, you have to provide the Benders' decomposition properties by calling the constructor
6832 * of the abstract base class scip::ObjBenderscut from within your constructor.
6833 * The properties you have to set have the following meaning:
6834 *
6835 * \par BENDERSCUT_NAME: the name of the Benders' decomposition cut method.
6836 * This name is used in the interactive shell to address the Benders' decomposition cut method.
6837 * Additionally, if you are searching for a Benders' decomposition cut method with SCIPfindBenderscut(), this name is
6838 * looked up. Names have to be unique: no two Benders' decomposition cut methods linked to the same Benders'
6839 * decomposition may have the same name.
6840 *
6841 * \par BENDERSCUT_DESC: the description of the Benders' decomposition cut method.
6842 * This string is printed as a description of the Benders' decomposition cut method in the interactive shell.
6843 *
6844 * \par BENDERSCUT_PRIORITY: the priority of the Benders' decomposition cut method.
6845 * In each of the Benders' decomposition subproblem solving loops, the included Benders' decomposition cut methods are
6846 * called in order of priority. The priority is important because once a cut is generated for a subproblem, no other
6847 * cuts are generated for that subproblem for that solving loop.
6848 * \n
6849 * The priority of the Benders' decomposition should be set according to the order in which the cut should be generated.
6850 * For example, the priority of the included cuts attempt to generation feasibility cuts (src/scip/benderscut_feas.c
6851 * and src/scip/benderscut_nogood.c) prior to attempting to generate optimality cuts.
6852 *
6853 * \par BENDERSCUT_LPCUT: Can this cut be applied to convex subproblems and convex relaxations of CIP subproblems?
6854 * Since the Benders' decomposition framework executes two different solving loops, one for convex subproblems and the
6855 * other for CIP subproblems, the Benders' decomposition cut methods must be partitioned by their suitability for each
6856 * subproblem type. If BENDERSCUT_LPCUT is set to TRUE, then this cut is only applied to convex subproblems and convex
6857 * relaxations of CIP subproblems.
6858 *
6859 * @section BENDERSCUT_DATA Benders' decomposition Data
6860 *
6861 * Below the header "Data structures" you can find a struct which is called "struct SCIP_BenderscutData".
6862 * In this data structure, you can store the data of your Benders' decomposition. For example, you should store the adjustable
6863 * parameters of the Benders' decomposition in this data structure. In a Benders' decomposition, user parameters for the
6864 * number of subproblems and an array to store the subproblem SCIP instances could be useful.
6865 * \n
6866 * Defining Benders' decomposition data is optional. You can leave the struct empty.
6867 *
6868 * @section BENDERSCUT_INTERFACE Interface Methods
6869 *
6870 * At the bottom of "benderscut_mybenderscut.c", you can find the interface method SCIPincludeBenderscutMybenderscut(),
6871 * which also appears in "benderscut_mybenderscut.h"
6872 * SCIPincludeBenderscutMybenderscut() is called by the user, if (s)he wants to include the Benders' decomposition,
6873 * i.e., if (s)he wants to use the Benders' decomposition in his/her application.
6874 *
6875 * This method only has to be adjusted slightly.
6876 * It is responsible for notifying SCIP of the presence of the Benders' decomposition. For this, you can either call SCIPincludeBenderscut(),
6877 * or SCIPincludeBenderscutBasic() since SCIP version 3.0. In the latter variant, \ref BENDERSCUT_ADDITIONALCALLBACKS "additional callbacks"
6878 * must be added via setter functions as, e.g., SCIPsetBenderscutCopy(). We recommend this latter variant because
6879 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
6880 * variant must be manually adjusted with every SCIP release containing new callbacks for Benders' decompositions in order to compile.
6881 *
6882 * If you are using Benders' decomposition cut data, you have to allocate the memory
6883 * for the data at this point. You can do this by calling:
6884 * \code
6885 * SCIP_CALL( SCIPallocBlockMemory(scip, &benderscutdata) );
6886 * \endcode
6887 * You also have to initialize the fields in "struct SCIP_BenderscutData" afterwards. For freeing the
6888 * Benders' decomposition cut data, see \ref BENDERSCUTFREE.
6889 *
6890 * You may also add user parameters for your Benders' decomposition, see \ref PARAM for how to add user parameters and
6891 * the method SCIPincludeBenderscutOpt() in src/scip/benderscut_opt.c for an example.
6892 *
6893 *
6894 * @section BENDERSCUT_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Benders' decomposition cut method
6895 *
6896 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
6897 * an operational algorithm.
6898 * They are passed together with the Benders' decomposition itself to SCIP using SCIPincludeBenderscut() or SCIPincludeBenderscutBasic(),
6899 * see @ref BENDERSCUT_INTERFACE.
6900 *
6901 * Benders' decomposition cut methods only one callback, @ref BENDERSCUTEXEC, that must be implemented.
6902 *
6903 * Additional documentation for the callback methods, in particular to their input parameters,
6904 * can be found in type_benderscut.h.
6905 *
6906 * @subsection BENDERSCUTEXEC
6907 *
6908 * The BENDERSCUTEXEC callback is called during the cut generation process within the Benders' decomposition subproblem
6909 * solving loop. This method must generate a cut for the given subproblem if the associated subsystem is not optimal
6910 * with respect to the checked master problem solution.
6911 *
6912 * When generating cuts, it is possible to store these within the SCIP_BendersData of the associated Benders'
6913 * decomposition. This is achieved by calling SCIPstoreBenderscutCons() (SCIPstoreBenderscutCut() if the Benders'
6914 * decomposition cut is added as a cutting plane instead as a constraint). The storing of cuts can be useful when using
6915 * the large neighbourhood Benders' search, where the cut generated in the sub-SCIP solve are transferred to the main
6916 * SCIP instance.
6917 *
6918 * The BENDERSCUTEXEC callback must return the result of the cut generation. The permissable results are:
6919 * - if the Benders' cut was not run (SCIP_DIDNOTRUN).
6920 * - if the Benders' cut was run, but there was an error in generating the cut (SCIP_DIDNOTFIND).
6921 * - if the Benders' decomposition cut algorithm has not generated a constraint or cut (SCIP_FEASIBLE).
6922 * - an additional constraint for the Benders' decomposition cut was generated (SCIP_CONSADDED).
6923 * - a cutting plane representing the Benders' decomposition cut was generated (SCIP_SEPARATED).
6924 *
6925 * If the BENDERSCUTEXEC callback returns SCIP_DIDNOTFIND due to an error in the cut generation, if no other subproblems
6926 * generate a cut during the same iteration of the Benders' decomposition algorithm, then this could result in an
6927 * error. It is possible to avoid the error by merging the subproblem into the master problem (see \ref
6928 * BENDERSPOSTSOLVE).
6929 *
6930 * @section BENDERSCUT_ADDITIONALCALLBACKS Additional Callback Methods of a Separator
6931 *
6932 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
6933 * implemented for most applications, they can be used, for example, to initialize and free private data.
6934 * Additional callbacks can either be passed directly with SCIPincludeBenderscut() to SCIP or via specific
6935 * <b>setter functions</b> after a call of SCIPincludeBenderscutBasic(), see also @ref BENDERSCUT_INTERFACE.
6936 *
6937 * @subsection BENDERSCUTFREE
6938 *
6939 * If you are using Benders' decomposition cut data (see \ref BENDERSCUT_DATA and \ref BENDERSCUT_INTERFACE), you have
6940 * to implement this method in order to free the Benders' decomposition cut data.
6941 *
6942 * If you have allocated memory for fields in your Benders' decomposition cut data, remember to free this memory
6943 * before freeing the Benders' decomposition data itself.
6944 * If you are using the C++ wrapper class, this method is not available.
6945 * Instead, just use the destructor of your class to free the member variables of your class.
6946 *
6947 * @subsection BENDERSCUTCOPY
6948 *
6949 * The BENDERSCUTCOPY callback is executed when a SCIP instance is copied, e.g. to
6950 * solve a sub-SCIP. By
6951 * defining this callback as
6952 * <code>NULL</code> the user disables the execution of the specified
6953 * separator for all copied SCIP instances. This may deteriorate the performance
6954 * of primal heuristics using sub-SCIPs.
6955 *
6956 * If the Benders' decomposition cuts are included by calling SCIPincludeBendersDefaultCuts() in the include method of
6957 * the Benders' decomposition implementation, such as SCIPincludeBendersDefault(), then it is not necessary to implement
6958 * BENDERSCUTCOPY. The copy method could be implemented to copy Benders' decomposition cut data from the original SCIP
6959 * instance to the sub-SCIP.
6960 *
6961 *
6962 * @subsection BENDERSCUTINIT
6963 *
6964 * The BENDERSCUTINIT callback is executed after the problem is transformed The Benders' decomposition cut method may,
6965 * e.g., use this call to initialize its Benders' decomposition cut data. The difference between the original and the
6966 * transformed problem is explained in "What is this thing with the original and the transformed problem about?" on \ref
6967 * FAQ.
6968 *
6969 * @subsection BENDERSCUTEXIT
6970 *
6971 * The BENDERSCUTEXIT callback is executed before the transformed problem is freed. In this method, the Benders'
6972 * decomposition cut method should free all resources that have been allocated for the solving process in
6973 * BENDERSCUTINIT.
6974 *
6975 * @subsection BENDERSCUTINITSOL
6976 *
6977 * The BENDERSCUTINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
6978 * begin. The Benders' decomposition implementation may use this call to initialize its branch-and-bound specific data.
6979 *
6980 * @subsection BENDERSCUTEXITSOL
6981 *
6982 * The BENDERSCUTEXITSOL callback is executed before the branch-and-bound process is freed. The Benders' decomposition
6983 * implementation should use this call to clean up its branch-and-bound data.
6984 *
6985 */
6986/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6987
6988/**@page CONF How to use conflict analysis
6989 *
6990 * Conflict analysis is a way to automatically use the information obtained from infeasible nodes
6991 * in the branch-and-bound tree.
6992 *
6993 * Once a node is declared infeasible, SCIP automatically tries to infer a constraint that explains the reason for the
6994 * infeasibility, in order to avoid similar situations later in the search. This explanation essentially consists of a
6995 * constraint stating that at least one of its variables should have a bound different from the current infeasible node,
6996 * because the current setting led to infeasibility. Clearly, all variables that are fixed in the current infeasible
6997 * node would yield such a constraint (since this leads to infeasibility). The key point rather is to infer a "small"
6998 * constraint that does the same job. SCIP handles this by several heuristics. For this, SCIP sets up a
6999 * so-called (directed) conflict graph. The nodes in this graph correspond to bound changes of variables and an arc (@a
7000 * 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
7001 * will have several ingoing arcs which represent all bound changes that have been used to infer (propagate) the bound
7002 * change in question. The graph also contains source nodes for each bound that has been changed during branching and an
7003 * artificial target node representing the conflict, i.e., the infeasibility. Essentially, SCIP heuristically constructs
7004 * a cut in this graph that involves few "branching nodes". For details on the techniques that SCIP uses,
7005 * we refer to the paper @par
7006 * Tobias Achterberg, Conflict Analysis in Mixed Integer Programming@n
7007 * Discrete Optimization, 4, 4-20 (2007)
7008 *
7009 * For conflict analysis to work well, the author of a \ref CONS "Constraint Handler" or a
7010 * \ref PROP "Propagator" has to implement three kinds of functionality:
7011 *
7012 * -# If one detects infeasibility, one should initiate conflict analysis, see \ref INITCONFS "below".
7013 * -# During propagation, one should call the right functions to fix variables.
7014 * -# One should implement the <em>so-called reverse propagation</em>.
7015 *
7016 * If this functionality is not implemented, SCIP will still work correctly, but cannot use the information of the constraint
7017 * handler or the propagator for conflict analysis. In this case, each bound reduction performed by the constraint
7018 * handler/propagator will be treated as if it had been a branching decision.
7019 *
7020 * @section INITCONFS Initiating Conflict Analysis
7021 *
7022 * If one detects infeasibility within propagation, one should do the following:
7023 * -# Call SCIPinitConflictAnalysis().
7024 * -# Inform SCIP about the variable bounds that are the reason for the detection of infeasibility
7025 * via the functions SCIPaddConflictLb(), SCIPaddConflictUb(), SCIPaddConflictBd(), or
7026 * SCIPaddConflictBinvar(). If there is more than one valid explanation of infeasibility, either one can be used.
7027 * Typically, smaller explanations tend to be better.
7028 * -# Call SCIPanalyzeConflict() from a propagator or SCIPanalyzeConflictCons() from a constraint
7029 * handler.
7030 *
7031 * This functionality allows SCIP to set up the conflict graph and perform a conflict analysis.
7032 *
7033 * @section Propagation
7034 *
7035 * When propagating variable domains, SCIP needs to be informed that the deduced variable bounds should be
7036 * used in conflict analysis. This can be done by the functions SCIPinferVarLbCons(),
7037 * SCIPinferVarUbCons(), and SCIPinferBinvarCons() for constraint handlers and SCIPinferVarLbProp(),
7038 * SCIPinferVarUbProp(), and SCIPinferBinvarProp() for propagators. You can pass one integer of
7039 * information that should indicate the reason of the propagation and can be used in reverse
7040 * propagation, see the next section.
7041 *
7042 * @section RESPROP Reverse Propagation
7043 *
7044 * Reverse Propagation is used to build up the conflict graph. Essentially, it provides an algorithm to detect the arcs
7045 * leading to a node in the conflict graph, i.e., the bound changes responsible for the new bound change deduced during
7046 * propagation. Reverse Propagation needs to be implemented in the RESPROP callback functions of
7047 * \ref CONSRESPROP "constraint handlers" or \ref PROPRESPROP "propagators".
7048 * These callbacks receive the following information: the variable which is under investigation (@p
7049 * infervar), the corresponding bound change (@p bdchgidx, @p boundtype), and the integer (@p inferinfo) that has been
7050 * supplied during propagation.
7051 *
7052 * One can use SCIPvarGetUbAtIndex() or SCIPvarGetLbAtIndex() to detect the bounds before or after the propagation that
7053 * should be investigated. Then the bounds that were involved should be passed to SCIP via SCIPaddConflictLb() and
7054 * SCIPaddConflictUb(). If there is more than one valid explanation of infeasibility, either one can be used.
7055 * Typically, smaller explanations tend to be better.
7056 *
7057 * Details and (more) examples are given in Sections @ref CONSRESPROP and @ref PROPRESPROP.
7058 *
7059 *
7060 * @section Example
7061 *
7062 * Consider the constraint handler @p cons_linearordering.c in the
7063 * \ref LOP_MAIN "linear ordering example"
7064 * (see @p example/LOP directory). This constraint handler propagates the equations \f$x_{ij} + x_{ji} =
7065 * 1\f$ and triangle inequalities \f$x_{ij} + x_{jk} + x_{ki} \leq 2\f$.
7066 *
7067 * When propagating the equation and <code>vars[i][j]</code> is fixed to 1, the constraint handler uses
7068 * \code
7069 * SCIP_CALL( SCIPinferBinvarCons(scip, vars[j][i], FALSE, cons, i*n + j, &infeasible, &tightened) );
7070 * \endcode
7071 * Thus, variable <code>vars[j][i]</code> is fixed to 0 (@p FALSE), and it passes <code>i*n + j </code> as @p inferinfo.
7072 *
7073 * When it propagates the triangle inequality and both <code>vars[i][j]</code> and <code>vars[j][k]</code>
7074 * are fixed to 1, the constraint handler uses
7075 * \code
7076 * SCIP_CALL( SCIPinferBinvarCons(scip, vars[k][i], FALSE, cons, n*n + i*n*n + j*n + k, &infeasible, &tightened) );
7077 * \endcode
7078 * 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
7079 * passed as <code>inferinfo</code>.
7080 *
7081 * In reverse propagation, the two cases can be distinguished by @p inferinfo: if it is less than @p n*n,
7082 * we deal with an equation, otherwise with a triangle inequality. The constraint handler can then extract the
7083 * indices @p i, @p j (and @p k in the second case) from inferinfo.
7084 *
7085 * In the first case, it has to distinguish whether <code>vars[i][j]</code> is fixed to 0 or 1 &ndash;
7086 * by calling SCIPaddConflictLb()
7087 * or SCIPaddConflictUb(), respectively, with variable <code>vars[j][i]</code>. In the second case, it is clear that the only
7088 * 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>
7089 * are fixed to 1. It then calls
7090 * SCIPaddConflictLb() for both <code>vars[k][i]</code> and <code>vars[j][k]</code>.
7091 */
7092
7093/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7094
7095/**@page REOPT How to use reoptimization
7096 *
7097 * The reoptimization feature of SCIP can be used to solve a sequence of optimization problems \f$(P_{i})_{i \in I}\f$ with
7098 * \f[
7099 * (P_i) \quad \min \{ c_i^T x \;|\; A^ix \geq b^i,\; x_{j} \in \mathbb{Z}\;\forall j \in \mathcal{I} \}
7100 * \f]
7101 * 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
7102 * function changes. To use reoptimization the user has to change the parameter <code>reoptimization/enable</code> to
7103 * <code>TRUE</code> before the solving process of the first problem of the sequence starts, i.e., in stage
7104 * <code>SCIP_STAGE_INIT</code> or <code>SCIP_STAGE_PROBLEM</code>. This can be done via the interactive shell or by
7105 * calling SCIPenableReoptimization(). In both cases SCIP changes some parameters and fixes them:
7106 * -# disable conflict analysis based on dual information
7107 * -# set the limit <code>maxorigsol</code> of stored solutions to zero because this is handled by a special solution tree provided
7108 * by the reoptimization feature itself
7109 * -# disable restarts (<code>presolving/maxrestarts = 0</code>)
7110 * -# disable multi-aggegations (<code>presolving/donotmultaggr = TRUE</code>)
7111 * -# disable dual reductions within presolvers and propagators (<code>misc/allowdualreds = FALSE</code>)
7112 * -# disable propagation with current cutoff bound (<code>misc/allowobjprop = FALSE</code>)
7113 *
7114 * In contrast to the presolving and propagating methods that are using dual information, performing strong branching is
7115 * allowed. The bound tightenings resulting from strong branching are handeled in a special way. After changing the objective
7116 * function and solving the modified problem the feasible region that was pruned by strong branching will be reconstructed
7117 * within the tree.
7118 *
7119 * If the reoptimization feature is enabled SCIP tries to reuse the search tree, especially the search frontier at the end
7120 * of the solving process, to speed up the solving process of the following problems. Therefore, the current release
7121 * provides the branching rule <code>branch_nodereopt</code> to reconstruct the tree. SCIP triggers a restart of the
7122 * reoptimization, i.e., solving the problem from scratch, if
7123 *
7124 * -# the stored search tree is too large,
7125 * -# the objective functions changed too much, or
7126 * -# the last \f$n\f$ optimal solution are updated solution of previous runs.
7127 *
7128 * The thresholds to trigger a restart can be set by the user:
7129 *
7130 * -# <code>reoptimization/maxsavednodes</code>
7131 * -# <code>reoptimization/delay</code>
7132 * -# <code>reoptimization/forceheurrestart</code>
7133 *
7134 * Before SCIP discards all the stored information and solves the problem from scratch it tries to compress the search
7135 * tree. Therefore, the current release provides compression heuristics that try to find a good and much smaller
7136 * representation of the current search tree.
7137 *
7138 * After a problem in the sequence of optimization problems was solved, the objective function can be changed in two ways:
7139 * -# Using the provided reader <code>reader_diff</code> the objective function can be changed via using the interactive
7140 * shell
7141 * \code
7142 * SCIP> read new_obj.diff
7143 * \endcode
7144 * or by calling SCIPreadDiff().
7145 * -# The objective function can be changed within the code. Therefore, the transformed problem needs to be freed by
7146 * calling SCIPfreeReoptSolve(). Afterwards, the new objective function can be installed by calling
7147 * SCIPchgReoptObjective().
7148 *
7149 * After changing the objective function the modified problem can be solved as usal.
7150 *
7151 * \note Currently, the compression heuristics used between two successive reoptimization runs only support pure binary
7152 * and mixed binary programs.
7153 *
7154 * For more information on reoptimization we refer to@par
7155 * Jakob Witzig@n
7156 * Reoptimization Techniques in MIP Solvers@n
7157 * Master's Thesis, Technical University of Berlin, 2014.
7158 */
7159
7160/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7161
7162/**@page CONCSCIP How to use the concurrent solving mode
7163 *
7164 * @section Overview
7165 *
7166 * In \SCIP 4.0 a new feature has been added that allows to run multiple \SCIP instances with different settings
7167 * on one problem in parallel. To use this feature \SCIP has to be compiled with an additional make option to
7168 * enable the threading functionality (e.g. TPI=tny, see \ref MAKE).
7169 * Then, a concurrent solve can be started by using the <code>concurrentopt</code> command instead of the <code>optimize</code> command
7170 * in the \SCIP shell, or by calling the interface function SCIPsolveParallel().
7171 * To configure the behavior of the concurrent solving mode there are new parameters in the category <code>concurrent/</code>
7172 * and <code>parallel/</code> which will be explained here shortly.
7173 *
7174 * @section CONTROLNTHREADS Controlling the number of threads
7175 *
7176 * The parameters <code>parallel/maxnthreads</code> and <code>parallel/minnthreads</code> can be used to configure the number of threads
7177 * that sould be used for solving. \SCIP will try to use the configured maximum number of threads. If the
7178 * problem that is currently read is too large \SCIP will automatically use fewer threads, but never
7179 * go below the configured minimum number of threads.
7180 *
7181 * @section USEEMPHSETTINGS Using emphasis settings
7182 *
7183 * The parameters <code>concurrent/scip.../prefprio</code> configure which concurrent solvers should be used.
7184 * The concurrent solver <code>scip</code> will use the same settings as the \SCIP instance configured by the user.
7185 * The other concurrent solvers, e.g. <code>scip-feas</code>, will load the corresponding emphasis setting.
7186 * The behavior of the prefprio parameter is as follows: If it is set to 1.0 for <code>scip-feas</code> and
7187 * <code>scip-opti</code>, and to 0.0 for every other concurrent solver, then the threads will be evenly
7188 * 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
7189 * 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
7190 * and the latter will use 3 threads of the 4 available threads.
7191 *
7192 * @section CUSTOMCONCSOLVERS Running custom solvers
7193 *
7194 * To use custom settings for the concurrent solvers there is the parameter <code>concurrent/paramsetprefix</code>. If custom parameters
7195 * 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).
7196 * The parameter settings must be named after the concurrent solvers, e.g. if only the concurrent solver <code>scip</code> is used
7197 * 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
7198 * starts at one for each of them, e.g. <code>scip-1</code> and <code>scip-feas-1</code>.
7199 */
7200
7201/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7202
7203/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7204
7205/**@page DECOMP How to provide a problem decomposition
7206 *
7207 * Most mixed-integer programs have sparse constraint matrices in the sense that most columns and rows have only very few nonzero entries,
7208 * maybe except for a few outlier columns/rows with many nonzeros.
7209 * 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
7210 * columns, but are otherwise independent.
7211 * The special case of completely independent subproblems (with no linking rows and columns), for example, can be solved by solving
7212 * the much smaller subproblems and concatenating their optimal solutions.
7213 * This case has already been integrated into SCIP as a successful presolving technique (see @ref cons_components.c).
7214 * Another use of decomposition within SCIP is the @ref BENDDECF "Benders Decomposition framework".
7215 *
7216 * Since SCIP 7.0, it is easier to pass user decompositions to SCIP that can be used within Benders decomposition or by user algorithms.
7217 * This page introduces the struct SCIP_DECOMP and gives examples how to create and use it.
7218 *
7219 * @section DECOMP_OVERVIEW Overview
7220 *
7221 * In the following, we present decompositions of mixed-integer programs. However, the generalization to Constraint Integer Programs is straightforward.
7222 *
7223 * 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,
7224 *
7225 * \f[
7226 * 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}})
7227 * \f]
7228 * 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$.
7229 * 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.
7230 * In other words, the inequality system \f$A x \geq b\f$ can be rewritten
7231 * with respect to a decomposition \f$\mathcal{D}\f$ by a suitable permutation of the rows
7232 * and columns of \f$A\f$ as equivalent system
7233 * \f[
7234 * \left(
7235 * \begin{matrix}
7236 * A_{[D^{\text{row}}_{1},D^{\text{col}}_{1}]} &
7237 * 0 &
7238 * \cdots &
7239 * 0 &
7240 * A_{[D^{\text{row}}_{1},L^{\text{col}}]}\\
7241 * 0 &
7242 * A_{[D^{\text{row}}_{2},D^{\text{col}}_{2}]} &
7243 * 0 &
7244 * 0 &
7245 * A_{[D^{\text{row}}_{2},L^{\text{col}}]}\\
7246 * \vdots &
7247 * 0 &
7248 * \ddots &
7249 * 0 &
7250 * \vdots\\
7251 * 0 &
7252 * \cdots &
7253 * 0 &
7254 * A_{[D^{\text{row}}_{k},D^{\text{col}}_{k}]} &
7255 * A_{[D^{\text{row}}_{k},L^{\text{col}}]}\\
7256 * A_{[L^{\text{row}},D^{\text{col}}_{1}]} &
7257 * A_{[L^{\text{row}},D^{\text{col}}_{2}]} &
7258 * \cdots &
7259 * A_{[L^{\text{row}},D^{\text{col}}_{k}]} &
7260 * A_{[L^{\text{row}},L^{\text{col}}]}
7261 * \end{matrix}
7262 * \right)
7263 * \left(
7264 * \begin{matrix}
7265 * x_{[D^{\text{col}}_{1}]}\\
7266 * x_{[D^{\text{col}}_{2}]}\\
7267 * \vdots\\
7268 * x_{[D^{\text{col}}_{k}]}\\
7269 * x_{[L^{\text{col}}]}
7270 * \end{matrix}
7271 * \right)
7272 * \geq
7273 * \left(
7274 * \begin{matrix}
7275 * b_{[D^{\text{row}}_{1}]}\\
7276 * b_{[D^{\text{row}}_{2}]}\\
7277 * \vdots\\
7278 * b_{[D^{\text{row}}_{k}]}\\
7279 * b_{[L^{\text{row}}]}
7280 * \end{matrix}
7281 * \right)
7282 * % A= \left(\begin{matrix}4&8&\frac{1}{2}\\\frac{3}{2}&4&1\\1&3&7\end{matrix}\right)
7283 * \f]
7284 * where we use the short hand syntax \f$A_{[I,J]}\f$ to denote
7285 * the \f$|I|\f$-by-\f$|J|\f$ submatrix that arises from the deletion of all entries
7286 * from \f$A\f$ except for rows \f$I\f$ and columns \f$J\f$,
7287 * for nonempty row
7288 * and column subsets \f$I\subseteq\{1,\dots,m\}\f$ and \f$J\subseteq\{1,\dots,n\}\f$.
7289 *
7290 *
7291 * @section DECOMP_USING Using a decomposition
7292 *
7293 * After passing one or more decompositions, see below, one can access all available decompositions with SCIPgetDecomps().
7294 * The labels can be obtained by calling SCIPdecompGetVarsLabels() and SCIPdecompGetConsLabels().
7295 * If some variables/constraints are not labeled, these methods will mark them as linking variables/constraints.
7296 * There are several methods to get more information about one decomposition, see @ref DecompMethods.
7297 *
7298 * A decomposition can be used to split the problem into several subproblems which, in general, are easier to solve.
7299 * For \f$q \in \{1,\dots,k\}\f$ the system
7300 * \f[
7301 * A_{[D^{\text{row}}_{q},D^{\text{col}}_{q}]}\; x_{[D^{\text{col}}_{q}]} \geq b_{[D^{\text{row}}_{q}]}
7302 * \f]
7303 * is part of subproblem \f$q\f$, the handling of the linking variables/constraints depends on the chosen application context.
7304 * For example, in the heuristic @ref heur_padm.c several smaller subproblems are solved multiple times to get a feasible solution.
7305 * Also the @ref BENDDECF "Benders' decomposition framework" was extended with release 7.0 to use user decompositions.
7306 *
7307 * @section DECOMP_CREATION Creation via SCIP-API
7308 *
7309 * There are two different ways to provide a decomposition in SCIP.
7310 * It can be created with the SCIP-API or it can be read from a file.
7311 *
7312 * To create it with the API, the user must first create a decomposition with SCIPcreateDecomp() specifying
7313 * whether the decomposition belongs to the original or transformed problem and the number of blocks.
7314 * Then the variables and constraints can be assigned to one block or to the linking rows/columns by calling
7315 * SCIPdecompSetVarsLabels() and SCIPdecompSetConsLabels(), respectively.
7316 * To complete the decomposition or to ensure that it is internally consistent, SCIPcomputeDecompVarsLabels() or
7317 * SCIPcomputeDecompConsLabels() can be called.
7318 * Note that SCIPcomputeDecompVarsLabels() will ignore the existing variable labels and computes again the labels based on the constraint labels only;
7319 * SCIPcomputeDecompConsLabels() works in the same way and ignores the existing constraint labels.
7320 *
7321 * After the decomposition has been successfully created, it can be saved for later use in the DecompStore using SCIPaddDecomp().
7322 * Access to all decompositions in the DecompStore is possible with SCIPgetDecomps().
7323 *
7324 * @section DECOMP_READDEC Reading a decomposition from a file
7325 *
7326 * Alternatively, after a problem has been read, a related decomposition can be read from a dec-file.
7327 * Please refer to the @ref reader_dec.h "DEC file reader" for further information about the required file format.
7328 * 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.
7329 *
7330 * @section DECOMP_BENDERS Use for Benders
7331 *
7332 * 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.
7333 * With this setting, the variable's labeling takes place giving precedence to its presence in linking constraints over its presence in named blocks.
7334 *
7335 * @section DECOMP_TRANS Decomposition after problem transformation
7336 *
7337 * As the problem's constraints are constantly changing, or possibly deleted, during presolving, the constraints' labeling must be triggered again.
7338 * Therefore, SCIP automatically transforms all user decompositions at the beginning of the root node based on the variables' labels.
7339 *
7340 * @section DECOMP_STATS Decomposition statistics
7341 *
7342 * Further useful measures and statistics about the decomposition are computed within SCIPcomputeDecompStats().
7343 * When the labeling process is concluded, the following measures are computed and printed:
7344 * - the number of blocks;
7345 * - the number of linking variables and linking constraints;
7346 * - the size of the largest as well as the smallest block;
7347 * - the area score:
7348 * This score is also used by GCG to rank decompositions during the automatic detection procedure.
7349 * For a decomposition
7350 * \f$\mathcal{D}=(D^{\text{row}},D^{\text{col}})\f$,
7351 * the area score is defined as
7352 * \f[
7353 * \text{areascore}(\mathcal{D}) = 1 - \frac{ \sum_{q=1}^k \lvert D^{\text{row}}_{q} \rvert
7354 * \lvert D^{\text{col}}_{q} \rvert + n\lvert L^{\text{row}} \rvert + m\lvert L^{\text{col}} \rvert -
7355 * \lvert L^{\text{row}} \rvert \lvert L^{\text{col}} \rvert }{mn}
7356 * \enspace.
7357 * \f]
7358 * In the case of a mixed-integer program, the area score intuitively measures the coverage of the rearranged matrix by 0's.
7359 * Decompositions with few linking variables and/or constraints and many small blocks \f$A_{[D^{\text{row}}_{q},D^{\text{col}}_{q}]}\f$
7360 * will have an area score close to \f$1\f$, whereas coarse decompositions of a matrix have smaller area scores.
7361 * The trivial decomposition with a single block has the worst possible area score of 0.
7362 * - the modularity:
7363 * This measure is used to assess the quality of the community structure within a decomposition.
7364 * The modularity of the decomposition is computed as follows:
7365 * \f[
7366 * \begin{aligned}
7367 * \sum_{q=1}^{k} \dfrac{e_{q}}{m} \left(1-\dfrac{e_{q}}{m}\right),
7368 * \end{aligned}
7369 * \f]
7370 * 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.
7371 * The presence of an inner edge is identified through the presence of a variable in a constraint,
7372 * both—the variable and the constraint—belonging to the same block.
7373 * - 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.
7374 * Note that the linking constraints are intentionally skipped in this computation.
7375 * \f$ G = (V,E) \f$ denotes a block graph, with vertex set \f$V\f$ and edge set \f$E\f$.
7376 * Each vertex in the graph represents a block in the decomposition; \f$V = \{v_{1},\dots,v_{k}\}\f$.
7377 * 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$
7378 * 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$.
7379 * From the constructed graph, the number of edges, articulation points and connected components are computed, together with the maximum and minimum degree.
7380 * Note that building the block graph can become computationally expensive with large and dense decompositions.
7381 * Thus, it is possible through a user parameter <code>decomposition/maxgraphedge</code> to define a maximum edge limit.
7382 * 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.
7383 *
7384 */
7385
7386/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7387
7388
7389/**@page BENDDECF How to use the Benders' decomposition framework
7390 *
7391 * Benders' decomposition is a very popular mathematical programming technique that is applied to solve structured
7392 * problems. Problems that display a block diagonal structure are particularly amenable to the application of Benders'
7393 * decomposition. In a purely mixed-integer linear setting, such problems are given by
7394 *
7395 * \f[
7396 * \begin{array}[t]{rllclcl}
7397 * \min & \displaystyle & c^{T}x & + & d^{T}y \\
7398 * & \\
7399 * \text{subject to} & \displaystyle & Ax & & & = & b \\
7400 * & \\
7401 * & \displaystyle & Tx & + & Hy & = & h \\
7402 * & \\
7403 * & & x & & & \in & \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
7404 * & & & & y & \in & \mathbb{R}^{m} \\
7405 * \end{array}
7406 * \f]
7407 *
7408 * The variables \f$x\f$ and \f$y\f$ are described as the first and second stage variables respectively. In the
7409 * classical use of Benders' decomposition, it is a requirement that the all second stage variables are continuous.
7410 * Extensions to the classical Benders' decomposition approach have permitted the use of more general second stage
7411 * problems.
7412 *
7413 * The application of Benders' decomposition to the above problem results in a subproblem, given by
7414 *
7415 * \f[
7416 * \begin{array}[t]{rll}
7417 * \min & \displaystyle & d^{T}y \\
7418 * & \\
7419 * \text{subject to} & \displaystyle & Hy = h - T\bar{x} \\
7420 * & \\
7421 * & & y \in \mathbb{R}^{m} \\
7422 * \end{array}
7423 * \f]
7424 *
7425 * where \f$\bar{x}\f$ is a solution vector of the first stage variables. As such, the subproblem is a problem only in
7426 * \f$y\f$. The dual solution to the subproblem, either an extreme point or extreme ray, is used to generate cuts that
7427 * are added to the master problem. Let \f$\lambda\f$ be the vector of dual variables associated with the set of
7428 * constraints from the subproblem. If, for a given \f$\bar{x}\f$, the subproblem is infeasible, then \f$\lambda\f$
7429 * corresponds to a dual ray and is used to produce the cut
7430 *
7431 * \f[
7432 * 0 \geq \lambda(h - Tx)
7433 * \f]
7434 *
7435 * which eliminates \f$\bar{x}\f$ from the master problem. If, for a given \f$\bar{x}\f$, the subproblem is feasible,
7436 * then \f$\lambda\f$ corresponds to a dual extreme point and is used to produce the cut
7437 *
7438 * \f[
7439 * \varphi \geq \lambda(h - Tx)
7440 * \f]
7441 *
7442 * where \f$\varphi\f$ is an auxiliary variable added to the master problem as an underestimator of the optimal
7443 * subproblem objective function value.
7444 *
7445 * Given \f$\Omega^{p}\f$ and \f$\Omega^{r}\f$ as the sets of dual extreme points and rays of the subproblem,
7446 * respectively, the Benders' decomposition master problem is given by
7447 *
7448 * \f[
7449 * \begin{array}[t]{rll}
7450 * \min & \displaystyle & c^{T}x + \varphi \\
7451 * & \\
7452 * \text{subject to} & \displaystyle & Ax = b \\
7453 * & \\
7454 * & \displaystyle & \varphi \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r}\\
7455 * & \\
7456 * & \displaystyle & 0 \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r} \\
7457 * & \\
7458 * & & x \in \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
7459 * & & \varphi \in \mathbb{R} \\
7460 * \end{array}
7461 * \f]
7462 *
7463 * @section BENDERFRAMEWORK Overview
7464 *
7465 * In \SCIP 6.0 a Benders' decomposition framework has been implemented.
7466 *
7467 * The current framework can be used to handle a Benders Decomposition of CIPs of the form
7468 *
7469 * \f[
7470 * \begin{array}[t]{rllclcl}
7471 * \min & \displaystyle & c^{T}x & + & d^{T}y \\
7472 * \text{subject to} & \displaystyle & g(x & , & y) & \in & [\ell,u] \\
7473 * & & x & & & \in & X \\
7474 * & & & & y & \in & Y \\
7475 * \end{array}
7476 * \f]
7477 * when either
7478 * - 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
7479 * - the first stage variables are of binary type: \f$ X \subseteq \{0,1\}^n \f$.
7480 *
7481 * This framework can be used in four different
7482 * ways: inputting an instance in the SMPS file format, using the default Benders' decomposition implementation
7483 * (see src/scip/benders_default.c), implementing a custom Benders' decomposition plugin (see \ref BENDER), or by using
7484 * the Benders' decomposition mode of GCG.
7485 * An overview of how to use each of these methods will be provided in this section.
7486 *
7487 * @section BENDERSSMPS Inputting an instance in the SMPS file format.
7488 *
7489 * As part of the Benders' decomposition framework development, a reader for instances in the SMPS file format has been
7490 * implemented (see src/scip/reader_smps.c). The details regarding the SMPS file format can be found at:
7491 *
7492 * Birge, J. R.; Dempster, M. A.; Gassmann, H. I.; Gunn, E.; King, A. J. & Wallace, S. W.
7493 * A standard input format for multiperiod stochastic linear programs
7494 * IIASA, Laxenburg, Austria, WP-87-118, 1987
7495 *
7496 * In brief, the SMPS file format involves three different files:
7497 * - A core file (.cor): a problem instance in MPS format that is the core problem of a stochastic program.
7498 * - A time file (.tim): partitions the variables and constraints into the different stages of the stochastic program
7499 * - A stochastic file (.sto): describes the scenarios for each stage.
7500 *
7501 * The STO reader (see src/scip/reader_sto.c) constructs the stochastic program using the information from the core and
7502 * time files. By default, the STO reader will construct the deterministic equivalent of the stochastic program. A
7503 * parameter is provided "reading/sto/usebenders" that will inform the STO reader to apply Benders' decomposition to the
7504 * input stochastic program.
7505 *
7506 * @section BENDERSDEFAULT Using the default Benders' decomposition plugin.
7507 *
7508 * A default implementation of a Benders' decomposition plugin has been included in \SCIP 6.0 (see
7509 * src/scip/benders_default.c). In order to use the default plugin, the user must create SCIP instances of the master
7510 * problem and subproblems. The subproblems must also contain a copy of the master problem variables, since these are
7511 * fixed to the master problem solution values during the subproblem solving loop. These SCIP instances for the master
7512 * and subproblems are passed to the default plugin by calling SCIPcreateBendersDefault().
7513 *
7514 * The mapping between the master and subproblem variables is performed automatically. The default solving and cut
7515 * generation methods are applied to solve the input problem. It is important to note that the mapping between the
7516 * master and subproblem variables relies on the variable names. The variables of the subproblem corresponding to
7517 * master problem variables must have the same name in both problems.
7518 *
7519 * The CAP (stochastic capacitated facility location problem) example demonstrates the use of the default Benders'
7520 * decomposition implementation within a project.
7521 *
7522 * @section BENDERSCUSTOM Implementing a custom Benders' decomposition implementation.
7523 *
7524 * A custom Benders' decomposition requires the implementation of a Benders' decomposition plugin. The key aspects for
7525 * implementing a custom Benders' decomposition plugin are explained in \ref BENDER.
7526 *
7527 * @section BENDERSGCG Using the Benders' decomposition mode of GCG
7528 *
7529 * In GCG 3.0, a Benders' decomposition mode has been implemented. This mode takes the decomposition found by the
7530 * detection schemes of GCG and applies Benders' decomposition. Using GCG it is possible to apply Benders' decomposition
7531 * to general problem without having to manually construct the decompositions.
7532 *
7533 */
7534
7535/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7536
7537/**@page PROBINGDIVING How to use probing and diving mode
7538 *
7539 * SCIP contains two methods to perform a temporary dive in the branch-and-bound tree: the diving mode and the probing mode.
7540 * Both methods enable the modification of variable bounds, addition of new constraints, or adjustments to the objective function.
7541 * 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.
7542 * 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.
7543 *
7544 * 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.
7545 * 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].
7546 * To reset all changes, the respective mode needs to be ended by calling SCIPendDive() and SCIPendProbing(), respectively.
7547 *
7548 * 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.
7549 * 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.
7550 * Similarly, the function SCIPpropagateProbing() might find globally valid bound changes, which are added to the main SCIP and considered in the subsequent solving process.
7551 * Another way to leverage insights found during probing or diving is to update pseudo costs during both modes, helping make better branching decisions.
7552 * This is controlled by setting the parameter "divingpscosts" to TRUE, which is done in the default settings of SCIP.
7553 * 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.
7554 * In some cases, such as when dealing with a numerically difficult instance, this might lead to a different LP state.
7555 * Finally, during probing, global variable statistics can be collected by calling SCIPenableVarHistory() after starting probing.
7556 * 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.
7557 *
7558 */
7559/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7560
7561/**@page OBJ Creating, capturing, releasing, and adding data objects
7562 *
7563 * Data objects (variables, constraints, rows, ... ) are subject to reference counting
7564 * to avoid expensive copying operations. This concept is similar to smart pointers.
7565 * Creating such an object (e.g., by calling SCIPcreateVar()) will set the
7566 * reference counter to one. Capturing an object (e.g., by calling SCIPcaptureVar()) increases the reference counter,
7567 * releasing it (e.g., by calling SCIPreleaseVar()) decreases the counter. If the reference counter gets zero, the
7568 * object will be destroyed automatically.
7569 *
7570 * Remember that a created data object is automatically captured. If the user
7571 * doesn't need the object anymore, (s)he has to call the object's release method.
7572 *
7573 * When a data object is added to SCIP (e.g., by calling SCIPaddVar()) , it is captured again, such that a
7574 * release call does not destroy the object. If SCIP doesn't need the object
7575 * anymore, it is automatically released.
7576 *
7577 * E.g., if the user calls
7578 * \code
7579 * SCIPcreateVar(); // reference counter 1
7580 * SCIPaddVar(); // reference counter 2
7581 * SCIPreleaseVar(); // reference counter 1
7582 * \endcode
7583 * the reference counter will be 1 afterwards, and the variable will be destroyed, if SCIP frees the problem.
7584 * If the user wants to use this variable, e.g. for extracting statistics after SCIP was finished, the user must not call
7585 * SCIPreleaseVar() right after adding the variable, but before terminating the program.
7586 */
7587
7588/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7589
7590/**@page PARAM How to add additional user parameters
7591 *
7592 * Users may add their own parameters to SCIP by calling SCIPaddXyzParam(). Using
7593 * this method, there are two possibilities for where to store the actual parameter value:
7594 * - If the given valueptr is NULL, SCIP stores the parameter value internally, and
7595 * the user can only access the value with the SCIPgetXyzParam() and
7596 * SCIPsetXyzParam() calls.
7597 * - If the given valueptr is not NULL, SCIP stores the parameter value at the given
7598 * address, and the user can directly manipulate the value at this address.
7599 * (S)he has to be careful with memory management in string parameters: when the
7600 * SCIPaddStringParam() method is called, the given address must hold a char*
7601 * pointer with value NULL. The default value is then copied into this pointer,
7602 * allocating memory with BMSallocMemoryArray(). If the parameter is changed, the
7603 * old string is freed with BMSfreeMemoryArray() and the new one is copied to a new
7604 * memory area allocated with BMSallocMemoryArray(). When the parameter is freed,
7605 * the memory is freed with BMSfreeMemoryArray().
7606 * The user should not interfere with this internal memory management. Accessing
7607 * the string parameter through the given valueptr is okay as long as it does not
7608 * involve reallocating memory for the string.
7609 *
7610 * In some cases, it is necessary to keep track of changes in a parameter.
7611 * If this is the case, the user can define a method by the PARAMCHGD callback and use this method as
7612 * the @c paramchgd parameter of the @c SCIPaddXyzParam() method, also giving a pointer to the data, which is
7613 * needed in this method, as @c paramdata. If this method is not NULL, it is called every time
7614 * the value of the parameter is changed.
7615 */
7616
7617/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7618
7619/**@page MEMORY Using the memory functions of SCIP
7620 *
7621 * SCIP provides three ways for allocating memory:
7622 * -# <b>block memory:</b> efficient handling of memory blocks of similar small sizes
7623 * -# <b>buffer memory:</b> efficient handling of memory that needs to locally be allocated and freed
7624 * -# <b>standard memory:</b> access to standard malloc/free
7625 *
7626 * <em>Whenever possible, the first two should be used, because of reasons detailed below.</em>
7627 *
7628 * In the following, we provide a brief description of these methods. We refer the reader to the dissertation of Tobias
7629 * Achterberg for more details. We also present best practice models.
7630 *
7631 * @section MEMBACK Background
7632 *
7633 * The main goals for providing such particular methods are:
7634 * - <em>Accounting:</em> Using its own functions, SCIP knows the total size of memory allocated internally and can change its
7635 * behavior: for instance, it can change to "memory saving mode" (using depth first search (DFS) and possibly do a garbage
7636 * collection). It also allows for keeping a memory limit.
7637 * - <em>Speed:</em> SCIP often needs to allocate a very large number of small blocks of similar sizes (often powers of
7638 * two). Depending on the operating system and compiler, the methods implemented in SCIP can be faster, since blocks
7639 * of the same size are grouped together. Especially at the end of the 1990ies the standard malloc/free methods were
7640 * quite ineffective. The experiments of Tobias Achterberg in 2007 show a speed improvement of 11 % when using block
7641 * memory.
7642 * - <em>Efficiency:</em> Since blocks are groups in sizes, the blocks do not need to store their sizes within each
7643 * block. In comparison, standard malloc/free stores the size using one word for each memory chunk. The price to pay
7644 * is that one needs to pass the size to the methods that free a block. In any case, the methods in SCIP can save
7645 * memory. Moreover, buffer memory is stored in similar places and not spread out, which also might help cache.
7646 * - <em>Debugging:</em> All of the possibilities provide methods to detect memory leaks. Together with tools like
7647 * valgrind, this can be quite effective in avoiding such problems.
7648 *
7649 * @n
7650 * @section BLKMEM Block memory
7651 *
7652 * SCIP offers its own block memory handling, which allows efficient handling of smaller blocks of memory in cases in
7653 * which many blocks of the same (small) size appear. This is adequate for branch-and-cut codes in which small blocks
7654 * of the same size are allocated and freed very often (for data structures used to store rows or branch-and-bound
7655 * nodes). Actually, most blocks allocated within SCIP have small sizes like 8, 16, 30, 32, 64. The idea is simple:
7656 * There is a separate list of memory blocks for each interesting small size. When allocating memory, the list is
7657 * checked for a free spot in the list; if no such spot exists, the list is enlarged. Freeing just sets the block to be
7658 * available. Very large blocks are handled separately. See the dissertation of Tobias Achterberg for more details.
7659 *
7660 * One important comment is that freeing block memory requires the size of the block in order to find the right list.
7661 *
7662 * The most important functions are
7663 * - SCIPallocBlockMemory(), SCIPallocBlockMemoryArray() to allocate memory
7664 * - SCIPfreeBlockMemory(), SCIPfreeBlockMemoryArray() to free memory
7665 *
7666 * An example code is:
7667 * @refsnippet{tests/src/misc/snippets.c,SnippetArrayAllocAndFree}
7668 * @n
7669 *
7670 * @section BUFMEM Buffer memory
7671 *
7672 * @subsection BUFMEMSTD Standard Buffer Memory
7673 *
7674 * In addition to block memory, SCIP offers buffer memory. This should be used if memory is locally used within a
7675 * function and freed within the same function. For this purpose, SCIP has a list of memory buffers that are reused for
7676 * this purpose. In this way, a very efficient allocation/freeing is possible.
7677 *
7678 * Note that the buffers are organized in a stack, i.e., freeing buffers in reverse order of allocation is faster.
7679 *
7680 * The most important functions are
7681 * - SCIPallocBuffer(), SCIPallocBufferArray() to allocate memory,
7682 * - SCIPfreeBuffer(), SCIPfreeBufferArray() to free memory.
7683 *
7684 * @subsection BUFMEMCLEAN Clean Buffer Memory
7685 *
7686 * SCIP 3.2 introduced a new type of buffer memory, the <em>clean buffer</em>. It provides memory which is initialized to zero
7687 * and requires the user to reset the memory to zero before freeing it. This can be used at performance-critical
7688 * places where only few nonzeros are added to a dense array and removing these nonzeros individually is much faster
7689 * than clearing the whole array. Similar to the normal buffer array, the clean buffer should be used for temporary memory
7690 * allocated and freed within the same function.
7691 *
7692 * The most important functions are
7693 * - SCIPallocCleanBufferArray() to allocate memory,
7694 * - SCIPfreeCleanBufferArray() to free memory.
7695 *
7696 * @n
7697 * @section STDMEM Standard memory
7698 *
7699 * SCIP provides an access to the standard C functions @c malloc and @c free with the additional feature of tracking
7700 * memory in debug mode. In this way, memory leaks can be easily detected. This feature is automatically activated in
7701 * debug mode.
7702 *
7703 * The most important functions are
7704 * - SCIPallocMemory(), SCIPallocMemoryArray() to allocate memory,
7705 * - SCIPfreeMemory(), SCIPfreeMemoryArray() to free memory.
7706 *
7707 * @n
7708 * @section MEMBESTPRACTICE Best Practice of Using Memory Functions
7709 *
7710 * Since allocating and freeing memory is very crucial for the speed and memory consumption of a program, it is
7711 * important to keep the following notes and recommendations in mind.
7712 *
7713 * @subsection GEN General Notes
7714 *
7715 * The following holds for all three types of memory functions:
7716 * - In debug mode, the arguments are checked for overly large allocations (usually arising from a bug). Note that all
7717 * arguments are converted to unsigned values of type @c size_t, such that negative sizes are converted into very
7718 * large values.
7719 * - The functions always allocate at least one byte and return non-NULL pointers if memory is available. In particular,
7720 * freeing is always possible.
7721 * - The freeing methods set the pointer to the memory to NULL.
7722 * - Debugging can be supported by using the compiler flags @p NOBLKMEM=true, @p NOBUFMEM=true, @p NOBLKBUFMEM=true
7723 * that turn off the usage of block memory, buffer memory, as well as block and buffer memory, respectively. Since,
7724 * the internal block and buffer memory is freed at the end (leaving no memory leaks), turning them off allows tools
7725 * like valgrind to find memory leaks.
7726 * - Moreover, additional checks can be turned on by defining @p CHECKMEM in memory.c.
7727 *
7728 * @n
7729 * @subsection DOS Things to do ...
7730 *
7731 * - Use buffer memory if your memory chunk can be allocated and freed within the same function.
7732 * - Use buffer and block memory wherever possible, because of the reasons explained above.
7733 * - Free memory in the reverse order in which it was allocated! For block and buffer memory this @b significantly
7734 * speeds up the code.
7735 * - Use as few memory allocations/freeing operations as possible, since these functions take a significant amount of time.
7736 *
7737 * @n
7738 * @subsection DONTS Things to avoid ...
7739 *
7740 * - Avoid the usage of standard memory, since SCIP is unaware of the size used in such blocks.
7741 * - Avoid reallocation with only slightly increased size, rather use a geometrically growing
7742 * size allocation. SCIPcalcMemGrowSize() is one way to calculate new sizes.
7743 * - Be careful with buffer memory reallocation: For single buffers, the memory is reallocated (using malloc); since
7744 * the actual space might be larger than what was needed at allocation time, reallocation sometimes comes without
7745 * extra cost. Note that reallocating block memory in most cases implies moving memory arround.
7746 */
7747
7748/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7749
7750/**@page DEBUG Debugging
7751 *
7752 * If you need to debug your own code that uses SCIP, here are some tips and tricks:
7753 *
7754 * - Use <b>asserts</b> in your code to show preconditions for the parameters, invariants and postconditions.
7755 * Assertions are boolean expressions which inevitably have to evaluate to <code>TRUE</code>. Consider the
7756 * following example:
7757 *
7758 * @refsnippet{src/scip/cons_linear.c,SnippetDebugAssertions}
7759 *
7760 * As you can see, both pointers and integers are checked for valid values at the beginning of the
7761 * function <code>consCatchEvent()</code>. This is particularly important for, e.g., array indices like
7762 * the variable <code>pos</code> in this example, where using the <code>consdata->vars[pos]</code>
7763 * pointer could result in unexspected behaviour
7764 * if the asserted precondition on <code>pos</code> were not matched and <code>pos</code> were an arbitrary index
7765 * outside the array range.
7766 *
7767 * - In order to activate assertions, use the <b>Debug mode</b> by compiling SCIP via
7768 * \code
7769 * cmake -DCMAKE_BUILD_TYPE=Debug
7770 * \endcode
7771 * or the Makefile equivalent
7772 * \code
7773 * make OPT=dbg
7774 * \endcode and run the code. See \ref CMAKE and \ref MAKE for further information about compiler options for SCIP.
7775 * As a rule of thumb, Spending only little extra time on
7776 * asserting preconditions saves most of the time spent on debugging!
7777 *
7778 * - Turn on <b>additional debug output</b> by adding the line
7779 * \code
7780 * #define SCIP_DEBUG
7781 * \endcode
7782 * at the top of SCIP files you want to analyze. This will output messages included in the code using
7783 * <code>SCIPdebugMsg(scip, ...)</code> (or <code>SCIPdebugMessage()</code>), see \ref EXAMPLE_1.
7784 * We recommend to also use <code>SCIPdebugMsg(scip, ...)</code> in your own code for being able to activate
7785 * debug output in the same way.
7786 * - If available on your system, we recommend to use a debugger like <code>gdb</code>
7787 * to trace all function calls on the stack,
7788 * display values of certain expressions, manually break the running code, and so forth.
7789 * - If available on your system, you can use software like <a href="http://valgrind.org">valgrind</a> to check for uninitialized
7790 * values or segmentation faults.
7791 * - For checking the usage of SCIP memory, you can use
7792 * <code>SCIPprintMemoryDiagnostic()</code>. This outputs memory that is currently in use,
7793 * which can be useful after a <code>SCIPfree()</code> call.
7794 * - 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>
7795 * (or <code>make NOBLKBUFMEM=true</code> if you are using the Makefile system.
7796 * Also for the Makefile system, do not forget to clean your code before with <code>make OPT=... LPS=... clean</code>)
7797 * Only with that change, valgrind (or similar) reliably helps
7798 * to detect leaked memory.
7799 * - If your code cuts off a feasible solution, but you do not know which component is responsible,
7800 * you can use the debugging mechanism (see \ref EXAMPLE_2). Therefore, a given solution is read and it
7801 * is checked for every reduction, whether the solution will be pruned globally.
7802 *
7803 * @section EXAMPLE_1 How to activate debug messages
7804 * For example, if we include a <code>\#define SCIP_DEBUG</code> at the top of \ref heur_oneopt.c, recompile SCIP
7805 * in Debug mode, and run the SCIP interactive shell to solve p0033.mps from the
7806 * <a href="http://miplib2010.zib.de/miplib3/miplib.html">MIPLIB 3.0</a> , we get some output like:
7807 *
7808 * \include debugexamples/example1.txt
7809 *
7810 * @section EXAMPLE_2 How to add a debug solution
7811 *
7812 * Continuing the example above, we finish the solving process.
7813 * The optimal solution can now be written to a file:
7814 * \include debugexamples/example2_1.txt
7815 *
7816 * If we afterwards recompile SCIP with the additional compiler flag <code>cmake -DDEBUGSOL=on</code> (<code>make DEBUGSOL=true</code> in the Makefile system),
7817 * set the parameter <code>misc/debugsol = check/p0033.sol</code>, and run SCIP again it will output:
7818 * \include debugexamples/example2_2.txt
7819 * Further debug output would only appear, if the solution was cut off in the solving process.
7820 */
7821
7822/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7823
7824/**@page STAGES SCIP stages
7825 *
7826 * The SCIP object goes through different stages during the solving process, the transitions from one to the next are presented in the following diagram.
7827 * \image html stages.png
7828 * More exhaustively, the stages are:
7829 * \code
7830 * SCIP_STAGE_INIT = 0, /**< SCIP data structures are initialized, no problem exists
7831 * SCIP_STAGE_PROBLEM = 1, /**< the problem is being created and modified
7832 * SCIP_STAGE_TRANSFORMING = 2, /**< the problem is being transformed into solving data space
7833 * SCIP_STAGE_TRANSFORMED = 3, /**< the problem was transformed into solving data space
7834 * SCIP_STAGE_INITPRESOLVE = 4, /**< presolving is initialized
7835 * SCIP_STAGE_PRESOLVING = 5, /**< the problem is being presolved
7836 * SCIP_STAGE_EXITPRESOLVE = 6, /**< presolving is exited
7837 * SCIP_STAGE_PRESOLVED = 7, /**< the problem was presolved
7838 * SCIP_STAGE_INITSOLVE = 8, /**< the solving process data is being initialized
7839 * SCIP_STAGE_SOLVING = 9, /**< the problem is being solved
7840 * SCIP_STAGE_SOLVED = 10, /**< the problem was solved
7841 * SCIP_STAGE_EXITSOLVE = 11, /**< the solving process data is being freed
7842 * SCIP_STAGE_FREETRANS = 12, /**< the transformed problem is being freed
7843 * SCIP_STAGE_FREE = 13 /**< SCIP data structures are being freed
7844 * \endcode
7845 * 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.
7846 */
7847
7848/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7849
7850/**@page TEST How to run automated tests with SCIP
7851 *
7852 * SCIP comes along with a set of useful tools that allow to perform automated tests. The
7853 * following is a step-by-step guide from setting up the test environment for evaluation and
7854 * customization of test runs.
7855 *
7856 *
7857 * @section SETUP Setting up the test environment
7858 *
7859 * At first you should create a file listing all problem instances that should be part of the test.
7860 * This file has to be located in the the directory <code>scip/check/testset/</code>
7861 * and has to have the file extension <code>.test</code>, e.g., <code>testrun.test</code>,
7862 * in order to be found by the <code>scip/check/check.sh</code> script.
7863 * \n
7864 * All test problems can be listed in the <code>test</code>-file by a relative path,
7865 * e.g., <code>../../problems/instance1.lp</code> or absolute path, e.g., <code>/home/problems/instance2.mps</code>
7866 * in this file. Only one problem should be listed on every line (since the command <code>cat</code> is used to parse this file).
7867 * Note that these problems have to be readable for SCIP in order to solve them.
7868 * However, you can use different file formats.
7869 *
7870 * Optionally, you can provide a solution file in the <code>scip/check/testset/</code> directory containing
7871 * known information about the feasibility and the best known objective values for the test instances.
7872 * SCIP can use these values to verify the results. The file has to have the same basename as the
7873 * <code>.test</code>-file, i.e., in our case <code>testrun.solu</code>. One line can only contain
7874 * information about one test instance. A line has to start with the type of information given:
7875 *
7876 * - <code>=opt=</code> stating that a problem name with an optimal objective value follows
7877 * - <code>=best=</code> stating that a problem name with a best know objective value follows
7878 * - <code>=inf=</code> stating that a problem name follows which is infeasible
7879 *
7880 * With these information types you can encode for an instance named <code>instance1.lp</code> the following
7881 * information:
7882 * - The instance has a known optimal (objective) value of 10.
7883 * \code
7884 * =opt= instance1 10
7885 * \endcode
7886 * - The instance has a best known solution with objective value 15.
7887 * \code
7888 * =best= instance1 15
7889 * \endcode
7890 * - The instance is feasible (but has no objective function or we don't know a solution value)
7891 * \code
7892 * =feas= instance1
7893 * \endcode
7894 * - The instance is infeasible.
7895 * \code
7896 * =inf= instance1
7897 * \endcode
7898 *
7899 * If you don't know whether the instance is feasible or not (so the status is unknown),
7900 * you can omit the instance in the <code>solu</code>-file or write
7901 * \code
7902 * =unkn= instance1
7903 * \endcode
7904 *
7905 * <b>Note that in all lines the file extension of the file name is omitted.</b>
7906 * \n
7907 * See the files <code>scip/check/testset/short.test</code> and <code>scip/check/testset/short.solu</code>
7908 * for an example of a <code>test</code>-file and its corresponding <code>solu</code>-file.
7909 *
7910 *
7911 *
7912 * @section STARTING Starting a test run
7913 *
7914 *
7915 * \code
7916 * make TEST=testrun test
7917 * \endcode
7918 *
7919 * in the SCIP root directory. Note that <code>testrun</code> is exactly the basename of our
7920 * <code>test</code>-file (<code>testrun.test</code>). This will cause SCIP to solve our test instances
7921 * one after another and to create various output files (see \ref EVAL).
7922 *
7923 *
7924 * @section EVAL Evaluating a test run
7925 *
7926 * During computation, SCIP automatically creates the directory <code>scip/check/results/</code>
7927 * (if it does not already exist) and stores the following output files there.
7928 *
7929 * \arg <code>*.out</code> - output of <code>stdout</code>
7930 * \arg <code>*.err</code> - output of <code>stderr</code>
7931 * \arg <code>*.set</code> - copy of the used settings file
7932 *
7933 * \arg <code>*.res</code> - ASCII table containing a summary of the computational results
7934 * \arg <code>*.tex</code> - TeX table containing a summary of the computational results
7935 * \arg <code>*.pav</code> - <a href="http://www.gamsworld.org/performance/paver/">PAVER</a> output
7936 *
7937 * The last three files in the above list, i.e., the files containing a summary of the computational results,
7938 * can also be generated manually. Therefore the user has to call the <code>evalcheck.sh</code> script in the
7939 * @c check directory with the corresponding @c out file as argument. For example, this may be useful if the user stopped the
7940 * test before it was finished, in which case the last three files will not be automatically generated by SCIP.
7941 *
7942 * The last column of the ASCII summary table contains the solver status. We distinguish the following statuses: (in order of priority)
7943 *
7944 * \arg abort: solver broke before returning solution
7945 * \arg fail: solver cut off a known feasible solution (value of the <code>solu</code>-file is beyond the dual bound;
7946 * especially if problem is claimed to be solved but solution is not the optimal solution)
7947 * <b>or</b> if a final solution check revealed a violation of one of the original constraints.
7948 * \arg ok: solver solved problem with the value in solu-file
7949 * \arg solved: solver solved problem which has no (optimal) value in solu-file (since we here cannot detect the direction
7950 * of optimization, it is possible that a solver claims an optimal solution which contradicts a known feasible solution)
7951 * \arg better: solver found solution better than known best solution (or no solution was noted in the <code>solu</code>-file so far)
7952 * \arg gaplimit, sollimit: solver reached gaplimit or limit of number of solutions (at present: only in SCIP)
7953 * \arg timeout: solver reached any other limit (like time or nodes)
7954 * \arg unknown: otherwise
7955 *
7956 * Additionally the <code>evalcheck.sh</code> script can generate a <code>solu</code>-file by calling
7957 * \code
7958 * ./evalcheck.sh writesolufile=1 NEWSOLUFILE=<solu-file> <out-file>
7959 * \endcode
7960 * where <code><solu-file></code> denotes the filename of the new file where the solutions shall be
7961 * (and <code><out-file></code> denotes the output (<code>.out</code>) files to evaluate).
7962 *
7963 * Another feature can be enabled by calling:
7964 * \code
7965 * ./evalcheck.sh printsoltimes=1 ...
7966 * \endcode
7967 * The output has two additional columns containing the solving time until the first and the best solution was found.
7968 *
7969 *
7970 * @b Note: The @em basename of all these files is the same and has the following structure
7971 * which allows us to reconstruct the test run:
7972 *
7973 * \code
7974 * check.<test name>.<binary>.<machine name>.<setting name>
7975 * \endcode
7976 *
7977 * \arg <<code>test name</code>> indicates the name of the the test file, e.g., <code>testrun</code>
7978 * \arg <<code>binary</code>> defines the used binary, e.g., <code>scip-3.2.0.linux.x86_64.gnu.opt.spx</code>
7979 * \arg <<code>machine name</code>> tells the name of the machine, e.g., <code>mycomputer</code>
7980 * \arg <<code>setting name</code>> denotes the name of the used settings, e.g., <code>default</code>
7981 * means the (SCIP) default settings were used
7982 *
7983 * Using the examples out of the previous listing the six file names would have the name:
7984 *
7985 * \code
7986 * check.testrun.scip-1.1.0.linux.x86.gnu.opt.spx.mycomputer.default.<out,err,set,res,tex,pav>
7987 * \endcode
7988 *
7989 *
7990 * @section USING Using customized setting files
7991 *
7992 * It is possible to use customized settings files for the test run instead of testing SCIP with default settings.
7993 * These have to be placed in the directory <code>scip/settings/</code>.
7994 *
7995 * @b Note: Several common user parameters such as, e.g., the time limit and node limit parameters,
7996 * <b>cannot</b> be controlled by the settings file, whose specifications would be overwritten
7997 * by optional command line arguments to the <code>make test</code> command, see @ref ADVANCED
7998 * for a list of available advanced testing options that have to be specified from the command line.
7999 *
8000 * @b Note: Accessing settings files in subfolders of the @c settings directory is currently not supported.
8001 *
8002 * To run SCIP with a custom settings file, say for example <code>fast.set</code>, we call
8003 *
8004 * \code
8005 * make TEST=testrun SETTINGS=fast test
8006 * \endcode
8007 *
8008 * in the SCIP root directory. It is possible to enter a list of settings files as a double-quoted,
8009 * comma-separated list of settings names as <code>fast</code> above, i.e. <code>SETTINGS="fast,medium,slow"</code>
8010 * will invoke the solution process for every instance with the three settings <code>fast.set, medium.set, slow.set</code>
8011 * before continuing with the next instance from the <code>.test</code>-file. This may come in handy if the
8012 * whole test runs for a longer time and partial results are already available.
8013 *
8014 *
8015 * @section ADVANCED Advanced options
8016 *
8017 * We can further customize the test run by specifying the following options in the <code>make</code> call:
8018 *
8019 * \arg <code>CONTINUE</code> - continue the test run if it was previously aborted [default: "false"]
8020 * \arg <code>DISPFREQ</code> - display frequency of the output [default: 10000]
8021 * \arg <code>FEASTOL</code> - LP feasibility tolerance for constraints [default: "default"]
8022 * \arg <code>LOCK</code> - should the test run be locked to prevent other machines from performing the same test run [default: "false"]
8023 * \arg <code>MAXJOBS=n</code> - run tests on 'n' cores in parallel. Note that several instances are solved in parallel, but
8024 * only one thread is used per job (parallelization is not that easy) [default: 1]
8025 * \arg <code>MEM</code> - memory limit in MB [default: 6144]
8026 * \arg <code>NODES</code> - node limit [default: 2100000000]
8027 * \arg <code>TIME</code> - time limit for each test instance in seconds [default: 3600]
8028 * \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]
8029 * \arg <code>THREADS</code> - the number of threads used for solving LPs, if the linked LP solver supports multithreading [default: 1]
8030 * \arg <code>VALGRIND</code> - run valgrind on the SCIP binary; errors and memory leaks found by valgrind are reported as fails [default: "false"]
8031 *
8032 *
8033 * @section COMPARE Comparing test runs for different settings
8034 *
8035 * Often test runs are performed on the basis of different settings. In this case, it is useful to
8036 * have a performance comparison. For this purpose, we can use the <code>allcmpres.sh</code> script in
8037 * the @c check directory.
8038 *
8039 * Suppose, we performed our test run with two different settings, say <code>fast.set</code> and
8040 * <code>slow.set</code>. Assuming that all other parameters (including the SCIP binary), were the same,
8041 * we may have the following <code>res</code>-files in the directory <code>scip/check/results/</code>
8042 *
8043 * \code
8044 * check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.fast.res
8045 * check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.slow.res
8046 * \endcode
8047 *
8048 * For a comparison of both computations, we simply call
8049 *
8050 * \code
8051 * allcmpres.sh results/check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.fast.res \
8052 * results/check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.slow.res
8053 * \endcode
8054 *
8055 * in the @c check directory. This produces an ASCII table on the console that provide a detailed
8056 * performance comparison of both test runs. Note that the first <code>res</code>-file serves as reference
8057 * computation. The following list explains the output.
8058 * (The term "solver" can be considered as the combination of SCIP with a specific setting file.)
8059 *
8060 * \arg <code>Nodes</code> - Number of processed branch-and-bound nodes.
8061 * \arg <code>Time</code> - Computation time in seconds.
8062 * \arg <code>F</code> - If no feasible solution was found, then '#', empty otherwise.
8063 * \arg <code>NodQ</code> - Equals Nodes(i) / Nodes(0), where 'i' denotes the current solver and '0' stands for the reference solver.
8064 * \arg <code>TimQ</code> - Equals Time(i) / Time(0).
8065 * \arg <code>bounds check</code> - Status of the primal and dual bound check.
8066 *
8067 * \arg <code>proc</code> - Number of instances processed.
8068 * \arg <code>eval</code> - Number of instances evaluated (bounds check = "ok", i.e., solved to optimality
8069 * within the time and memory limit and result is correct). Only these instances are used in the calculation
8070 * of the mean values.
8071 * \arg <code>fail</code> - Number of instances with bounds check = "fail".
8072 * \arg <code>time</code> - Number of instances with timeout.
8073 * \arg <code>solv</code> - Number of instances correctly solved within the time limit.
8074 * \arg <code>wins</code> - Number of instances on which the solver won (i.e., the
8075 * solver was at most 10% slower than the fastest solver OR had the best
8076 * primal bound in case the instance was not solved by any solver within
8077 * the time limit).
8078 * \arg <code>bett</code> - Number of instances on which the solver was better than the
8079 * reference solver (i.e., more than 10% faster).
8080 * \arg <code>wors</code> - Number of instances on which the solver was worse than the
8081 * reference solver (i.e., more than 10% slower).
8082 * \arg <code>bobj</code> - Number of instances on which the solver had a better primal
8083 * bound than the reference solver (i.e., a difference larger than 10%).
8084 * \arg <code>wobj</code> - Number of instances on which the solver had a worse primal
8085 * bound than the reference solver (i.e., a difference larger than 10%).
8086 * \arg <code>feas</code> - Number of instances for which a feasible solution was found.
8087 * \arg <code>gnodes</code> - Geometric mean of the processed nodes over all evaluated instances.
8088 * \arg <code>shnodes</code> - Shifted geometric mean of the processed nodes over all evaluated instances.
8089 * \arg <code>gnodesQ</code> - Equals nodes(i) / nodes(0), where 'i' denotes the current
8090 * solver and '0' stands for the reference solver.
8091 * \arg <code>shnodesQ</code> - Equals shnodes(i) / shnodes(0).
8092 * \arg <code>gtime</code> - Geometric mean of the computation time over all evaluated instances.
8093 * \arg <code>shtime</code> - Shifted geometric mean of the computation time over all evaluated instances.
8094 * \arg <code>gtimeQ</code> - Equals time(i) / time(0).
8095 * \arg <code>shtimeQ</code> - Equals shtime(i) / shtime(0).
8096 * \arg <code>score</code> - N/A
8097 *
8098 * \arg <code>all</code> - All solvers.
8099 * \arg <code>optimal auto settings</code> - Theoretical result for a solver that performed 'best of all' for every instance.
8100 * \arg <code>diff</code> - Solvers with instances that differ from the reference solver in the number of
8101 * processed nodes or in the total number of simplex iterations.
8102 * \arg <code>equal</code> - Solvers with instances whose number of processed nodes and total number of
8103 * simplex iterations is equal to the reference solver (including a 10% tolerance) and where no timeout
8104 * occured.
8105 * \arg <code>all optimal</code> - Solvers with instances that could be solved to optimality by
8106 * <em>all</em> solvers; in particular, no timeout occurred.
8107 *
8108 * Since this large amount of information is not always needed, one can generate a narrower table by calling:
8109 * \code
8110 * allcmpres.sh short=1 ...
8111 * \endcode
8112 * where <code>NodQ</code>, <code>TimQ</code> and the additional comparison tables are omitted.
8113 *
8114 * If the <code>res</code>-files were generated with the parameter <code>printsoltimes=1</code>
8115 * we can enable the same feature here as well by calling:
8116 * \code
8117 * allcmpres.sh printsoltimes=1 ...
8118 * \endcode
8119 * As in the evaluation, the output contains the two additional columns of the solving time until the first and the best solution was found.
8120 *
8121 * @section STATISTICS Statistical tests
8122 *
8123 * The \c allcmpres script also performs two statistical tests for comparing different settings: For deciding whether
8124 * more feasible solutions have been found or more instances have been solved to optimality or not, we use a McNemar
8125 * test. For comparing the running time and number of nodes, we use a variant of the Wilcoxon signed rank test. A
8126 * detailed explanation can be found in the PhD thesis of Timo Berthold (Heuristic algorithms in global MINLP solvers).
8127 *
8128 * @subsection McNemar McNemar test
8129 *
8130 * Assume that we compare two settings \c S1 and \c S2 with respect to the number of instances solved to optimality
8131 * within the timelimit. The null hypothesis would be "Both settings lead to an equal number of instances being solved
8132 * to optimality", which we would like to disprove. Let \f$n_1\f$ be the number of instances solved by setting \c S1
8133 * 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
8134 * McNemar test statistic is
8135 * \f[
8136 * \chi^2 = \frac{(n_1 - n_2)^2}{n_1 + n_2}.
8137 * \f]
8138 * Under the null hypothesis, \f$\chi^2\f$ is chi-squared distributed with one degree of freedom. This allows to compute
8139 * a \f$p\f$-value as the probability for obtaining a similar or even more extreme result under the null hypothesis.
8140 * More explicitly, \c allcmpres uses the following evaluation:
8141 * - \f$0.05 < p\f$: The null hypothesis is accepted (marked by "X").
8142 * - \f$0.005 < p \leq 0.05\f$: The null hypothesis might be false (marked by "!").
8143 * - \f$0.0005 < p \leq 0.005\f$: The null hypothesis can be false (marked by "!!").
8144 * - \f$p \leq 0.0005\f$: The null hypothesis is very likely false (marked by "!!!").
8145 *
8146 * As an example consider the following output:
8147 * \code
8148 * McNemar (feas) x2 0.0000, 0.05 < p X
8149 * McNemar (opt) x2 6.0000, p ~ (0.005, 0.05] !
8150 * \endcode
8151 * Here, \c x2 represents \f$\chi^2\f$.
8152 *
8153 * In this case, the test with respect to the number of found feasible solutions is irrelevant, since their number is
8154 * equal. In particular, the null hypothesis gets accepted (i.e., there is no difference in the settings - this is
8155 * marked by "X").
8156 *
8157 * With respect to the number of instances solved to optimality within the timelimit, we have that \f$0.005 < p <=
8158 * 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
8159 * settings perform differently; this is marked by "!". In the concrete case, we have 230 instances, all of which are
8160 * solved by setting \c S2, but only 224 by setting \c S1.
8161 *
8162 * @subsection Wilcoxon Wilcoxon signed rank test
8163 *
8164 * Assume that we compare two settings \c S1 and \c S2 with respect to their solution times (within the time limit). We
8165 * generate a sorted list of the ratios of the run times, where ratios that are (absolutely or relatively) within 1\%
8166 * of 1.0 are discarded, and ratios between 0.0 and 0.99 are replaced with their negative inverse in order to
8167 * obtain a symmetric distribution for the ratios around the origin.
8168 * We then assign ranks 1 to \c N to the remaining \c N data points in nondecreasing
8169 * order of their absolute ratio. This yields two groups \c G1
8170 * 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
8171 * setting \c S1 is faster). Then the sums of the ranks in groups \c G1 and \c G2 are computed, yielding values \c R1
8172 * and \c R2, respectively.
8173 *
8174 * The Wilcoxon test statistic is then
8175 * \f[
8176 * z = \frac{\min(R1, R2) - \frac{N(N+1)}{4}}{\sqrt{\frac{N(N+1)(2N+1)}{24}}},
8177 * \f]
8178 * which we assume to be (approximately) normally distributed (with zero mean) and allows to compute the probability
8179 * \f$p\f$ that one setting is faster than the other. (Note that for \f$N \leq 60\f$, we apply a correction by
8180 * subtracting 0.5 from the numerator).
8181 *
8182 * As an example consider the following output:
8183 * \code
8184 * Wilcoxon (time) z -0.1285, 0.05 <= p X
8185 * Wilcoxon (nodes) z -11.9154, p < 0.0005 !!!
8186 * \endcode
8187 * While the \f$z\f$-value is close to zero for the run time, it is extremely negative regarding the solving nodes. This latter
8188 * 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
8189 * nodes than setting \c S2 is negligible (this null hypothesis is rejected - marked by "!!!").
8190 *
8191 * However, the null hypothesis is not rejected with respect to the run time. In the concrete case, setting \c S1 has a
8192 * 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
8193 * 0.88. Still - the null hypothesis is not rejected.
8194 *
8195 * @section SOLVER Testing and Evaluating using GAMS
8196 *
8197 * Analogously to the target <code>test</code> there is another target to run automated tests with <a href="http://www.gams.com/">gams</a>
8198 * \code
8199 * make testgams GAMSSOLVER=xyz
8200 * \endcode
8201 * For this target, the option GAMSSOLVER has to be given to specify the name of a GAMS solver to run, e.g. GAMSSOLVER=SCIP.
8202 * Additional advanced options specific to this target are:
8203 * GAMS to specify the GAMS executable (default: gams),
8204 * GAP to specify a gap limit (default: 0.0),
8205 * CLIENTTMPDIR to specify a directory where GAMS should put its scratch files (default: /tmp),
8206 * 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).
8207 * The following options are NOT supported (and ignored): DISPFREQ, FEASTOL, LOCK.
8208 * 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).
8209 *
8210 * Note: This works only if the referred programs are installed globally on your machine.
8211 *
8212 * The above options like <code>TIME</code> are also available for gams.
8213 *
8214 * After the testrun there should be an <code>.out</code>, an <code>.err</code> and a <code>.res</code> file
8215 * with the same basename as described above.
8216 *
8217 * Furthermore you can also use the script <code>allcmpres.sh</code> for comparing results.
8218 *
8219 * @section PYTHON Testing using PySCIPOpt
8220 *
8221 * To run a python script that uses PySCIPOpt with <code>make test</code> or <code>make testcluster</code>, one has to
8222 * specify the python code to execute with the option <code>EXECUTABLE=/full/path/to/python-script.py</code>.
8223 * Note that <code>python-script.py</code> must be an executable file.
8224 * In addition, one <b>must</b> specify which python it should run with the option <code>PYTHON=my-python</code>.
8225 * The reason for this is that one usually installs PySCIPOpt in a virtual environment, thus only the python of the
8226 * virtual environment will work with the python script.
8227 *
8228 * The scripts work in such a way that they pass information to SCIP like the setting files, the instance name, and some other options.
8229 * It is the responsability of the python script <code>python-script.py</code> to parse this information.
8230 * Thus, you need to modify your python script to read the setting files and the other options provided by the testing scripts.
8231 * An example of how to do this is provided in <code>scip/check/scip-runner.py</code>.
8232 * One should either modify <code>scip/check/scip-runner.py</code> or include the <code>build_model()</code> function
8233 * into your script to correctly read the options passed by the scripts.
8234 *
8235 * An example of how to run the tests is
8236 * \code
8237 * make test EXECUTABLE=/full/path/to/scip/check/scip-runner.py PYTHON=python
8238 * \endcode
8239 */
8240
8241/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
8242
8243/**@page COUNTER How to use SCIP to count/enumerate feasible solutions
8244 *
8245 * SCIP is capable of computing (count or enumerate) the number of feasible solutions of a given constraint integer
8246 * program. In case continuous variables are present, the number of feasible solutions for the projection to the
8247 * integral variables is counted/enumerated. This means, an assignment to the integer variables is counted if the
8248 * remaining problem (this is the one after fixing the integer variables w.r.t. to this assignment) is feasible.
8249 *
8250 * As a first step you have to load or create your problem in the usual way. In case of using the
8251 * interactive shell, you use the <code>read</code> command:
8252 *
8253 * <code>SCIP&gt; read &lt;file name&gt;</code>
8254 *
8255 * Afterwards you can count the number of feasible solution with the command <code>count</code>.
8256 *
8257 * <code>SCIP&gt; count</code>
8258 *
8259 * @note After completing the counting process, SCIP will terminate with status <tt>infeasible</tt>. This is intended
8260 * behavior, because SCIP counts solutions by the following internal mechanism. Each feasible solution that is found is
8261 * reported as infeasible to the SCIP core. This avoids that SCIP performs reductions based on the primal bound that
8262 * could cut off suboptimal feasible solutions, which would then be missing in the count. However, as a result, the
8263 * SCIP core has not found any feasible solutions during the search and reports status <tt>infeasible</tt>.
8264 *
8265 * By default, SCIP only counts the number of solutions but does not store (enumerate) them. If you are interested in
8266 * that see \ref COLLECTALLFEASEBLES.
8267 *
8268 * @note Since SCIP version 2.0.0 you do not have to worry about the impact of dual reductions anymore. These are
8269 * automatically turned off. The only thing you should switch off are restarts. These restarts can lead to a wrong
8270 * counting process. We recommend using the counting settings which can be set in the interactive shell as follows:
8271 *
8272 * <code>SCIP&gt; set emphasis counter</code>
8273 *
8274 * The SCIP callable library provides an interface method SCIPcount() which allows users to count the number of feasible
8275 * solutions to their problem. The method SCIPsetParamsCountsols(), which is also located in cons_countsols.h, loads the
8276 * predefined counting settings to ensure a safe count. The complete list of all methods that can be used for counting
8277 * via the callable library can be found in cons_countsols.h.
8278 *
8279 *
8280 * @section COUNTLIMIT Limit the number of solutions which should be counted
8281 *
8282 * It is possible to give a (soft) upper bound on the number solutions that should be counted. If this upper bound is
8283 * exceeded, SCIP will be stopped. The name of this parameter is <code>constraints/countsols/sollimit</code>. In
8284 * the interactive shell this parameter can be set as follows:
8285 *
8286 * <code>SCIP&gt; set constraints countsols sollimit 1000</code>
8287 *
8288 * In case you are using the callable library, this upper bound can be assigned by calling SCIPsetLongintParam() as follows:
8289 *
8290 * \code
8291 * SCIP_CALL( SCIPsetLongintParam( scip, "constraints/countsols/sollimit", 1000) );
8292 * \endcode
8293 *
8294 *
8295 * The reason why this upper bound is soft comes from the fact that, by default, SCIP uses a technique called unrestricted
8296 * subtree detection. Using this technique it is possible to detect several solutions at once. Therefore, it can happen
8297 * that the solution limit is exceeded before SCIP is stopped.
8298 *
8299 * @section COLLECTALLFEASEBLES Collect all feasible solutions
8300 *
8301 * Per default SCIP only counts all feasible solutions. This means, these solutions are not stored. If you switch the
8302 * parameter <code>constraints/countsols/collect</code> to TRUE (the default value is FALSE) the detected solutions are
8303 * stored. Changing this parameter can be done in the interactive shell
8304 *
8305 * <code>SCIP&gt; set constraints countsols collect TRUE</code>
8306 *
8307 * as well as via the callable library
8308 *
8309 * \code
8310 * SCIP_CALL( SCIPsetBoolParam( scip, "constraints/countsols/collect", TRUE) );
8311 * \endcode
8312 *
8313 * @note The solution which are collected are stored w.r.t. the active variables. These are the variables which got not
8314 * removed during presolving.
8315 *
8316 * In case you are using the interactive shell you can write all collected solutions to a file as follows
8317 *
8318 * <code>SCIP&gt; write allsolutions &lt;file name&gt;</code>
8319 *
8320 * In that case the sparse solutions are unrolled and lifted back into the original variable space.
8321 *
8322 * The callable library provides a method which gives access to all collected sparse solutions. That is,
8323 * SCIPgetCountedSparseSolutions(). The sparse solutions you get are defined w.r.t. active variables. To get solutions
8324 * w.r.t. to the original variables. You have to do two things:
8325 *
8326 * -# unroll each sparse solution
8327 * -# lift each solution into original variable space by extending the solution by those variable which got removed
8328 * during presolving
8329 *
8330 * The get the variables which got removed during presolving, you can use the methods SCIPgetFixedVars() and
8331 * SCIPgetNFixedVars(). The method SCIPgetProbvarLinearSum() transforms given variables, scalars and constant to the
8332 * corresponding active variables, scalars and constant. Using this method for a single variable gives a representation
8333 * for that variable w.r.t. the active variables which can be used to compute the value for the considered solution (which
8334 * is defined w.r.t. active variables).
8335 *
8336 * For that complete procedure you can also check the source code of
8337 * \ref SCIP_DECL_DIALOGEXEC(SCIPdialogExecWriteAllsolutions) "SCIPdialogExecWriteAllsolutions()" cons_countsols.c which
8338 * does exactly that.
8339 *
8340 *
8341 * @section COUNTOPTIMAL Count number of optimal solutions
8342 *
8343 * If you are interested in counting the number of optimal solutions, this can be done with SCIP using the
8344 * <code>count</code> command by applying the following steps:
8345 *
8346 * -# Solve the original problem to optimality and let \f$c^*\f$ be the optimal value
8347 * -# Added the objective function as constraint with left and right hand side equal to \f$c^*\f$
8348 * -# load the adjusted problem into SCIP
8349 * -# use the predefined counting settings
8350 * -# start counting the number of feasible solutions
8351 *
8352 * If you do this, SCIP will collect all optimal solutions of the original problem.
8353 *
8354 */
8355
8356/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
8357
8358/** @page SYMMETRY How to use symmetry handling in SCIP
8359 *
8360 * Symmetry handling is an important feature of SCIP that allows to discard symmetric subproblems from the
8361 * branch-and-bound tree, and thus, can substantially reduce the running time. To handle symmetries, SCIP
8362 * automatically detects symmetries and then applies (combinations of) symmetry handling methods.
8363 *
8364 * @section SYMDETECT Symmetry detection
8365 *
8366 * SCIP can detect two types of symmetries: permutation symmetries and signed permutation symmetries.
8367 * In a purely integer linear setting
8368 * \f[
8369 * \max \{ c^{\top} x : Ax \leq b,\; x \in \mathbb{Z}^n \},
8370 * \f]
8371 * a permutation symmetry is a permutation \f$\gamma\f$ of \f$\{1,\dots,n\}\f$ that acts on vector \f$x\f$ by
8372 * permuting its coordinates via \f$\gamma(x) = (x_{\gamma^{-1}(1)}, \dots, x_{\gamma^{-1}(n)})\f$
8373 * such that
8374 *
8375 * -# \f$\gamma\f$ leaves the objective invariant, i.e., \f$c^{\top}x = c^{\top}\gamma(x)\f$, and
8376 * -# \f$\gamma\f$ maps feasible solutions onto feasible solutions, i.e., \f$Ax \leq b\f$ if and only
8377 * if \f$A\gamma(x) \leq b\f$.
8378 *
8379 * Signed permutation symmetries are defined similarly and allow to also handle symmetries arising from
8380 * reflections of the feasible region along standard hyperplanes, e.g., mapping \f$x_i\f$ to \f$-x_i\f$
8381 * and keeping the remaining entries of a solution vector \f$x\f$ invariant. Formally, a signed permutation \f$\gamma\f$
8382 * is a permutation of the set \f$\{\pm 1, \dots, \pm n\}\f$ such that \f$\gamma(-i) = - \gamma(i)\f$
8383 * for all \f$i \in \{1,\dots,n\}\f$. A signed permutation acts on a vector \f$x\f$ as
8384 * \f$\gamma(x) = (\mathrm{sgn}(\gamma^{-1}(1))x_{|\gamma^{-1}(1)|},\dots,
8385 * \mathrm{sgn}(\gamma^{-1}(n))x_{|\gamma^{-1}(n)|})\f$,
8386 * where \f$\mathrm{sgn}(\cdot)\f$ is the sign function. The remaining properties of a symmetry are the same.
8387 * It is possible to switch between these two types of symmetries via the
8388 * parameter <code>propagating/symmetry/symtype</code>.
8389 * Moreover, to detect more general signed permutations, one can shift variables with a
8390 * bounded domain to be centered at the origin. This way, also variables with, e.g., domains \f$[1,2]\f$
8391 * and \f$[0,1]\f$ can be symmetric. In SCIP, we implement this shift only within symmetry detection
8392 * to find generalized signed permutations; the variable bounds of the problem itself remain unchanged.
8393 *
8394 * Since both definitions depend on the feasible region of the integer program, which is unknown
8395 * in general, SCIP only computes symmetries that leave the formulation of the optimization problem
8396 * invariant. To detect such formulation symmetries, SCIP builds an auxiliary colored graph whose
8397 * color-preserving automorphisms correspond to symmetries of the integer program. The symmetries of
8398 * the graph, and thus of the integer program, are then computed by an external graph automorphism
8399 * library that needs to be linked to SCIP. Currently, SCIP ships with two such libraries: The graph
8400 * automorphism libraries bliss or nauty/traces are the basic workhorses to detect symmetries. Moreover, one can use
8401 * sassy, a graph symmetry preprocessor which passes the preprocessed graphs to bliss or nauty/traces.
8402 * The current default is to use bliss in combination with sassy for symmetry detection.
8403 *
8404 * @note To detect symmetries, SCIP needs to be built with sassy/bliss, which can be achieved
8405 * by using the options <code>SYM=sassy</code> and <code>-DSYM=sassy</code> in the Makefile and CMake
8406 * system, respectively.
8407 *
8408 * Besides purely integer linear problems, SCIP also supports symmetry detection for general
8409 * constraint mixed-integer programs containing most of the constraint types that can be handled
8410 * by SCIP. In particular, symmetries of mixed-integer nonlinear problems can be detected.
8411 * Moreover, symmetries can also be detected in code containing customized constraints.
8412 * To this end, a suitable callback needs to be implemented, see \ref SYMDETECTCUSTOM.
8413 *
8414 * @subsection SYMPROCESS Processing symmetry information
8415 *
8416 * After symmetries have been computed, SCIP has access to a list \f$\gamma_1,\dots,\gamma_m\f$ of
8417 * (signed) permutations that generate a group \f$\Gamma\f$ of symmetries of the optimization problem. That
8418 * is, SCIP has not access to all permutations in \f$\Gamma\f$, but only a set of generators. Based
8419 * on these generators, SCIP analyzes the group \f$\Gamma\f$ and checks whether it can be split into
8420 * independent factors. That is, whether there exist subgroups \f$\Gamma_1,\dots,\Gamma_k\f$ of
8421 * \f$\Gamma\f$ that act on pairwise independent sets of variables such that \f$\bigcup_{i=1}^k \Gamma_i = \Gamma\f$.
8422 * In this case, SCIP can handle the symmetries of the different subgroups independently. In particular,
8423 * different subgroups can be treated by different symmetry handling methods.
8424 *
8425 * @section SYMMETHODS Symmetry handling methods
8426 *
8427 * Most symmetry handling methods available in SCIP have only been implemented for ordinary permutation symmetries,
8428 * and not for signed permutation symmetries. In the following, we silently assume that the described methods
8429 * deal with ordinary permutation symmetries if not mentioned differently.
8430 * To handle symmetries, SCIP uses three different classes of methods, which we detail below.
8431 *
8432 * @subsection SYMCONSS Static symmetry handling constraints for binary variable domains
8433 *
8434 * SCIP contains three constraint handlers for handling symmetries of binary variables: the symresack,
8435 * orbisack, and orbitope constraint handler. Given a symmetry \f$\gamma\f$,
8436 * the symresack constraint handler enforces that a solution vector \f$x\f$ is not lexicographically
8437 * smaller than its image \f$\gamma(x)\f$. This constraint is enforced by a propagation algorithm
8438 * and separating inequalities. Moreover, given the disjoint cycle decomposition of \f$\gamma\f$,
8439 * SCIP checks, for each cycle of \f$\gamma\f$, whether all variables in the cycle are contained
8440 * in set packing or partitioning constraints. If this is the case, specialized inequalities can
8441 * be separated.
8442 *
8443 * In case the permutation \f$\gamma\f$ is an involution, i.e., \f$\gamma(\gamma(x)) = x\f$,
8444 * specialized separation and propagation algorithms can be used, which are implemented in the
8445 * orbisack constraint handler. For orbisack constraints, also facet-defining inequalities of the
8446 * convex hull of all binary points \f$x\f$ being not lexicographically smaller than \f$\gamma(x)\f$
8447 * can be separated. Since the coefficients in these inequalities grow exponentially large which might
8448 * cause numerical instabilities, the separation of these inequalities is disabled by default, but can be
8449 * enabled via the parameter <code>constraints/orbisack/orbiSeparation</code>. Furthermore, to avoid
8450 * numerical instabilities, the parameter <code>constraints/orbisack/coeffbound</code> controls the
8451 * maximum absolute value of a coefficient in separated facet-defining inequalities.
8452 *
8453 * Finally, the orbitope constraint handler is able to handle symmetries of special symmetric groups \f$\Gamma\f$.
8454 * For orbitopes to be applicable, the affected variables need to be arranged in a matrix \f$X\f$ such that
8455 * the symmetries in \f$\Gamma\f$ permute the columns of \f$X\f$. Symmetries are then handled by orbitope
8456 * constraints by enforcing to only compute solution matrices \f$X\f$ whose columns are sorted lexicographically
8457 * non-increasingly. To this end, a propagation algorithm is used and inequalities are separated. In case
8458 * the variables of each row of the matrix \f$X\f$ are contained in a set packing or partitioning constraint,
8459 * specialized propagation and separation routines are used.
8460 *
8461 * @subsection SYMPROP Dynamic symmetry handling by propagation
8462 *
8463 * Static symmetry handling enforces a lexicographic ordering on the variable solution vectors.
8464 * The pro of that approach, is that throughout the solving process, the same lexicographic ordering constraint
8465 * is used. This means that already during presolving certain symmetry reductions can be made.
8466 * The con of this approach is that an ordering of the variables for lexicographic comparisons have to be made
8467 * before solving. Consequently, if reductions of certain variable domains are found, but these variables are compared
8468 * late by the lexicographic comparison order, the effect for symmetry handling is very slim.
8469 *
8470 * Dynamic symmetry handling addresses this issue by propagating symmetry handling constraints, where the variable
8471 * comparison ordering are determined while solving, attempting to make strong symmetry handling reductions early on.
8472 * Dynamic symmetry handling removes feasible solutions of the problem, while it is guaranteed that at least one
8473 * symmetric solution remains feasible.
8474 *
8475 * Whether dynamic or static symmetry handling methods are used, is determined by the boolean parameter
8476 * <code>propagating/symmetry/usedynamicprop</code>.
8477 * SCIP features three dynamic symmetry handling methods.
8478 * SCIP only provides propagation methods for handling these symmetries,
8479 * and the methods work on variables with arbitrary (so also non-binary) variable domains.
8480 *
8481 * -# Orbitopal reduction is the dynamic counterpart of orbitopal fixing. This method can be used if the variables
8482 * can be arranged without duplicates in a matrix, and symmetries permute the columns of this matrix. This method
8483 * propagates the variable domains such that solutions in matrix-form have lexicographically decreasing columns,
8484 * with respect to the dynamically chosen row and column order.
8485 * Orbitopal reduction respects the parameter <code>propagating/symmetry/detectorbitopes</code>.
8486 * -# Lexicographic reduction is the dynamic counterpart of symresack and orbisack propagation.
8487 * Lexicographic reduction respects the parameter <code>propagating/symmetry/addsymresacks</code>.
8488 * At the moment, the implementation of this method is the only one that allows to also handle signed permutation
8489 * symmetries.
8490 * -# Orbital reduction is a generalization of orbital fixing that also works for non-binary variable domains.
8491 * Orbital reduction respects the 2-bit of the bitset <code>misc/usesymmetry</code>.
8492 * See \ref SYMMETHODSELECT <method selection>. Since there is no static counterpart, this method ignores
8493 * <code>propagating/symmetry/usedynamicprop</code>.
8494 *
8495 * In all cases, the dynamic variable ordering is derived from the branching decisions.
8496 * In particular, at different branch-and-bound tree nodes, a different variable ordering can be active.
8497 * Since the symmetries are handled for independent factors of the symmetry group, a different variable ordering method
8498 * can be used for handling symmetries in different factors. In SCIP, the same method is used for orbital reduction and
8499 * for lexicographic reduction, which means that these two methods are compatible and can be used simultaneously in the
8500 * same factor. Orbitopal reduction uses a different method.
8501 *
8502 * As SCIP might restart the branch-and-bound process, which removes information regarding the branching decisions,
8503 * we need to make sure that correct reductions are found after a restart.
8504 * If a restart occurs, static symmetry handling methods are preserved. Since dynamic symmetry handling methods
8505 * depend on the branch-and-bound tree structure, and because the prior branch-and-bound tree is removed,
8506 * the dynamic symmetry handling methods are disabled after a restart.
8507 *
8508 * @subsection SYMSST SST cuts
8509 *
8510 * The Schreier-Sims table (SST) is a table that contains certain information about symmetry groups
8511 * and can be used, among others, to derive symmetry handling inequalities. The corresponding SST cuts
8512 * are symmetry handling inequalities that are defined iteratively in rounds \f$r = 1,\dots,R\f$.
8513 * In each round \f$r\f$, a leader variable \f$\ell_r\f$ is selected and the group
8514 * \f$\Gamma_r = \{ \gamma \in \Gamma : \gamma(\ell_i) = \ell_i \text{ for all } i = 1,\dots,r-1\}\f$
8515 * is considered. Then, the symmetry handling inequalities of round \f$r\f$ are defined as
8516 * \f$x_{\ell_r} \geq x_j\f$ for all \f$j \in \{\gamma(i) : i \in \{1,\dots,n\}\}\f$.
8517 * The latter set is called the orbit of leader \f$\ell_r\f$.
8518 *
8519 * SST cuts admit many degrees of freedom. In particular, they are not limited to binary variables
8520 * but can be used for arbitrary variable types. A user can gain control over the selection process of
8521 * SST cuts via several parameters. For instance,
8522 *
8523 * - <code>sstleadervartype</code> is a bitset encoding the variable types of leaders: the 1-bit models binary,
8524 * the 2-bit integer, the 4-bit implicit integer, and the 8-bit continuous variables. That is, a value
8525 * of 9 models that the leader can be a binary or continuous variable.
8526 * - <code>sstleaderrule</code> ranges from 0 to 2 and models whether a leader is the first variable in
8527 * its orbit, the last variable in its orbit, or a variable with most conflicts with other variables in
8528 * the orbit, respectively.
8529 * - <code>ssttiebreakrule</code> ranges from 0 to 2 and models whether an orbit of minimum size, maximum
8530 * size or with most variables being in conflict to the leader is selected, respectively.
8531 * - <code>sstmixedcomponents</code> whether SST cuts are also applied if a symmetries do not only affect
8532 * variables of a single type.
8533 * - <code>sstaddcuts</code> whether SST cuts are added to the problem. If no cuts are added, only
8534 * binary variables might be fixed to 0 if they are in conflict with the leader.
8535 *
8536 * @subsection SYMMETHODSELECT Selecting symmetry handling methods
8537 *
8538 * The symmetry handling methods explained above can be enabled and disabled via the parameter
8539 * <code>misc/usesymmetry</code>, which encodes the enabled methods via a bitset that ranges between 0
8540 * and 7: the 1-bit encodes symmetry handling constraints, the 2-bit encodes orbital reduction, and the
8541 * 4-bit encodes SST cuts. For example, <code>misc/usesymmetry = 3</code> enables symmetry handling
8542 * constraints and orbital reduction, whereas <code>misc/usesymmetry = 0</code> disables symmetry handling.
8543 * In the following, we explain how the combination of different symmetry handling methods works.
8544 *
8545 * The default strategy of SCIP is to handle symmetries via the bitset value 7, i.e., symmetry handling
8546 * constraints, orbital reduction, and SST cuts are enabled. To make sure that the different methods are
8547 * compatible, the following steps are carried out:
8548 *
8549 * -# SCIP determines independent subgroups \f$\Gamma_1,\dots,\Gamma_k\f$ as described in \ref SYMPROCESS.
8550 * Then, for each subgroup \f$\Gamma_i\f$, different symmetry handling methods can be applied.
8551 * -# For each subgroup \f$\Gamma_i\f$, a heuristic is called that checks whether orbitopes are applicable
8552 * to handle the entire subgroup. If yes, this subgroup is handled by orbitopes and no other
8553 * symmetry handling methods.
8554 * -# Otherwise, if parameter <code>propagating/symmetry/detectsubgroups</code> is <code>TRUE</code>
8555 * and <code>propagating/symmetry/usedynamicprop</code> is <code>FALSE</code>, a
8556 * heuristic is called to detect whether "hidden" orbitopes are present. That is, whether some but not
8557 * all symmetries of \f$\Gamma_i\f$ can be handled by orbitopes. If sufficiently many symmetries can
8558 * be handled by orbitopes, orbitopes are applied and, if parameter <code>propagating/symmetry/addweaksbcs</code>
8559 * is TRUE, some compatible SST cuts are added, too. Besides this, no further symmetry handling methods
8560 * are applied for \f$\Gamma_i\f$.
8561 * -# Otherwise, orbital reduction is used. If <code>propagating/symmetry/usedynamicprop</code> and
8562 * <code>propagating/symmetry/addsymresacks</code> are <code>TRUE</code>, then also the dynamic lexicographic
8563 * reduction method is used.
8564 * -# Otherwise, if the majority of variables affected by \f$\Gamma_i\f$ are non-binary, SST cuts are applied
8565 * to handle \f$\Gamma_i\f$. No further symmetry handling methods are applied for \f$\Gamma_i\f$.
8566 *
8567 * @note If orbital reduction is enabled, a factor \f$\Gamma_i\f$ can always be handled by this method.
8568 * As such, by default, no SST cuts will be added.
8569 *
8570 * @note Depending on the setting of <code>misc/usesymmetry</code>, it might be possible that a symmetry component is
8571 * not handled. For instance, if only orbitopal reduction is used
8572 * (i.e., <code>propagating/symmetry/detectorbitopes</code> is set to 1),
8573 * and if a symmetry component is no orbitope, no symmetry is handled for that component at all.
8574 *
8575 *
8576 * @subsection SYMTIMING Controlling the timing of symmetry computation
8577 *
8578 * Since presolving might both remove and introduce formulation symmetries, the timing of computing symmetries
8579 * can be changed via the parameters <code>propagating/symmetry/addconsstiming</code> and
8580 * <code>propagating/symmetry/ofsymcomptiming</code>.
8581 * The first specifies the moment at which symmetries handling methods must be determined.
8582 * The second specifies the moment at which the symmetries must be computed.
8583 * If the second is triggered at a later moment than the first, the symmetries are computed just before determining
8584 * the symmetry handling methods, so the first parameter is the dominant parameter.
8585 * Both parameters take values 0, 1, or 2, corresponding to computing symmetries before presolving,
8586 * during presolving, or when the symmetry handling methods are applied first, respectively.
8587 *
8588 *
8589 * @subsection SYMDETECTCUSTOM Symmetry detection for customized constraints
8590 *
8591 * To detect (signed) permutation symmetries, SCIP requests from each constraint present in the problem to be solved
8592 * a node and edge colored graph whose symmetries correspond to the symmetries of the corresponding constraint.
8593 * This information is provided by two callbacks, the SCIP_DECL_CONSGETPERMSYMGRAPH callback for permutation
8594 * symmetries and the SCIP_DECL_CONSGETSIGNEDPERMSYMGRAPH callback for signed permutation symmetries. If a
8595 * constraint handler does not implement one of these callbacks, SCIP will not detect symmetries of the corresponding
8596 * type.
8597 *
8598 * In the following, we briefly describe how such a symmetry detection graph looks like for linear constraints.
8599 * Afterwards, we mention the basic setup of the symmetry detection graphs and how the callbacks could be implemented
8600 * for customized constraints.
8601 *
8602 * @subsubsection SYMDETECTLINEAR Symmetry detection graphs for linear constraints
8603 *
8604 * Simple permutation symmetries of a linear constraint \f$\sum_{i = 1}^n a_ix_i \leq \beta\f$ are given
8605 * by permutations that exchange equivalent variables with the same coefficients. These symmetries can be encoded
8606 * by a graph with the following structure. For every variable \f$x_i\f$, the graph contains a node \f$v_i\f$
8607 * that receives a color that uniquely determines the type of the variable (lower/upper bound, objective coefficient,
8608 * integrality). Moreover, the graph contains a node \f$w\f$ that receives a color corresponding to the right-hand side
8609 * \f$\beta\f$. Node \f$w\f$ is then connected with all nodes corresponding to variables. Edge \f$\{w,v_i\}\f$ then
8610 * receives a color corresponding to the coefficient \f$a_i\f$. Then, every automorphism of this graph corresponds to a
8611 * permutation symmetry of the linear constraint.
8612 *
8613 * For signed permutation symmetries, almost the same construction can be used. The only difference is that also
8614 * nodes \f$v_{-i}\f$ need to be introduced that correspond to the negation of variable \f$x_i\f$. These negated
8615 * variable nodes are then also connected with node \f$\beta\f$ and the corresponding edge receives color \f$-a_i\f$.
8616 * Finally, to make sure that the corresponding symmetry corresponds to a signed permutation \f$\gamma\f$, i.e.,
8617 * \f$\gamma(-i) = - \gamma(i)\f$, one also needs to add the edges \f$\{v_i,v_{-i}\}\f$ that remain uncolored.
8618 * Note that the color of node \f$v_{-i}\f$ also needs to uniquely determine the negated variable bounds and
8619 * objective coefficient.
8620 *
8621 * @subsubsection SYMDETECTRULES Principles for building symmetry detection graphs
8622 *
8623 * A symmetry detection graph of a constraint needs to have the property that each of its automorphisms corresponds
8624 * to a (signed) permutation of the constraint. Moreover, the corresponding constraint handler of the constraints
8625 * needs to be encoded in the graph to make sure that only symmetries between equivalent constraints can be computed.
8626 * Among others, this can be achieved by assigning the nodes and edges appropriate colors. To make sure that the
8627 * colors are compatible between the different symmetry detection graphs, SCIP automatically determines the colors of
8628 * nodes and edges based on information that is provided by the user (or the creator of the graph).
8629 *
8630 * A pointer to a globally maintained symmetry detection graph is provided to the callbacks. The nodes and edges of the
8631 * graph of a constraint are added to this global graph.
8632 * The nodes of the graph need to be added via the functions <code>SCIPaddSymgraphValnode()</code>
8633 * and <code>SCIPaddSymgraphConsnode()</code>. The first function can be used to create nodes corresponding to
8634 * a numerical value like \f$\beta\f$ in the above example, the latter function creates a node corresponding to
8635 * a provided constraint. This ensures that only symmetry detection graphs from the same constraint handler
8636 * can be isomorphic. The colors of the nodes are then computed automatically by SCIP based on the information
8637 * that is provided the functions creating these nodes. This ensures that node colors are compatible.
8638 *
8639 * Edges are created via the function <code>SCIPaddSymgraphEdge()</code> which receives, among others, the
8640 * indices of created nodes. Note that there is no function for creating variable nodes as SCIP automatically
8641 * creates nodes for variables. Their indices can be accessed via <code>SCIPgetSymgraphVarnodeidx()</code> for
8642 * original variables and <code>SCIPgetSymgraphNegatedVarnodeidx()</code> for negated variables used for
8643 * signed permutations. The edges between variables \f$x_i\f$ and \f$-x_i\f$ are also automatically present
8644 * in the symmetry detection graph for signed permutation symmetries. The function <code>SCIPaddSymgraphEdge()</code>
8645 * also takes a numerical value as argument, which allows to assign an edge a weight (e.g., \f$a_i\f$
8646 * as in the above example).
8647 *
8648 * Moreover, special nodes, so-called operator nodes, can be added via <code>SCIPaddSymgraphOpnode()</code>.
8649 * Such nodes allow to model special structures of a constraint, which allow to have more degrees of freedom in
8650 * creating symmetry detection graphs. Different operators are distinguished by an integral value.
8651 * Their encoding is thus similar to the one of nodes created by <code>SCIPaddSymgraphValnode()</code>.
8652 * In computing colors, operator nodes are treated differently though, which allows to distinguish
8653 * operator 2 from the numerical value 2.
8654 *
8655 * @subsubsection SYMDETECTEXAMPLES Example for creating symmetry detection callbacks
8656 *
8657 * 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
8658 * stable set problem can be modeled via the integer program
8659 * \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\]
8660 * Suppose a user wants to implement a constraint handler <code>cons_stableset</code> that enforces a solution to define
8661 * a stable set in \f$G\f$, e.g., by propagation methods and separating edge and clique inequalities.
8662 * Then, the symmetries of the constraint are the weight-preserving automorphisms of the underlying graph \f$G\f$.
8663 * The symmetry detection graph thus can be almost a copy of \f$G\f$.
8664 *
8665 * In our construction, we introduce for each node \f$v\f$ of the graph an operator node \f$v'\f$.
8666 * Moreover, for each edge \f$\{u,v\}\in E\f$, we add the edges \f$\{u',v'\}\f$ to the symmetry detection graph.
8667 * To identify the symmetry detection graph as derived from <code>cons_stableset</code>, we add a constraint node
8668 * that is connected with all operator nodes, which preserves the automorphisms of \f$G\f$. Finally, each
8669 * node \f$v'\f$ is connected with the corresponding variable node for \f$x_v\f$ by an edge.
8670 *
8671 * In the following, we present a code snippet showing how to implement the above mentioned symmetry detection graph.
8672 * We assume that the constraint data <code>consdata</code> contains the following fields
8673 *
8674 * - <code>nnodes</code> number of nodes in graph;
8675 * - <code>nedges</code> number of edges in graph;
8676 * - <code>first</code> array containing the first nodes of each edge;
8677 * - <code>second</code> array containing the second nodes of each edge;
8678 * - <code>weights</code> array containing for each node its corresponding weight;
8679 * - <code>vars</code> array containing a binary variable for each node modeling whether node is present in stable set.
8680 *
8681 * The code for creating the symmetry detection callback could then look like this.
8682 *
8683 * \code{.c}
8684 * #define NODEOP 1
8685 * static
8686 * SCIP_DECL_CONSGETPERMSYMGRAPH(consGetPermsymGraphStableSet)
8687 * {
8688 * SCIP_CONSDATA* consdata;
8689 * int* idx;
8690 * int vidx;
8691 * int nnodes;
8692 * int v;
8693 *
8694 * consdata = SCIPconsGetData(cons);
8695 * nnodes = consdata->nnodes;
8696 *
8697 * SCIP_CALL( SCIPallocBufferArray(scip, &idx, nnodes + 1) );
8698 *
8699 * // create operator nodes and constraint node
8700 * for( v = 0; v < nnodes; ++v )
8701 * {
8702 * SCIP_CALL( SCIPaddSymgraphOpnode(scip, graph, NODEOP, &idx[v]) );
8703 * }
8704 * SCIP_CALL( SCIPaddSymgraphConsnode(scip, graph, cons, 0.0, 0.0, &idx[nnodes]) );
8705 *
8706 * // add edges of underlying graph
8707 * for( v = 0; v < consdata->nedges; ++v )
8708 * {
8709 * SCIP_CALL( SCIPaddSymgraphEdge(scip, graph, idx[consdata->first[v]], idx[consdata->second[v]], FALSE, 0.0) );
8710 * }
8711 *
8712 * // connect nodes with constraint node
8713 * for( v = 0; v < nnodes; ++v )
8714 * {
8715 * SCIP_CALL( SCIPaddSymgraphEdge(scip, graph, idx[v], nodeidx[nnodes], FALSE, 0.0) );
8716 * }
8717 *
8718 * // connect operator nodes with variable nodes, assign edges weight of node
8719 * for( v = 0; v < nnodes; ++v )
8720 * {
8721 * vidx = SCIPgetSymgraphVarnodeidx(scip, graph, consdata->vars[v]);
8722 * SCIP_CALL( SCIPaddSymgraphEdge(scip, graph, idx[v], vidx, TRUE, consdata->weights[v]) );
8723 * }
8724 *
8725 * SCIPfreeBufferArray(scip, &idx);
8726 *
8727 * return SCIP_OKAY;
8728 * }
8729 * \endcode
8730 */
8731
8732/**@page LICENSE License
8733 *
8734 * \verbinclude LICENSE
8735 */
8736
8737/**@page FAQ Frequently Asked Questions (FAQ)
8738 * \htmlinclude faq/faq.inc
8739 */
8740
8741
8742/**@page PARAMETERS List of all SCIP parameters
8743 *
8744 * This page list all parameters of the current SCIP version. This list can
8745 * easily be generated by SCIP via the interactive shell using the following command:
8746 *
8747 * <code>SCIP&gt; set save &lt;file name&gt;</code>
8748 *
8749 * or via the function call:
8750 *
8751 * <code>SCIP_CALL( SCIPwriteParams(scip, &lt;file name&gt;, TRUE, FALSE) );</code>
8752 *
8753 * \verbinclude parameters.set
8754 */
8755
8756/**@page INTERFACES Interfaces
8757 *
8758 * There are several ways of accessing the \SCIP Optimization Suite from other software packages or programming
8759 * platforms.
8760 *
8761 *
8762 * @section FILEFORMATS File formats
8763 *
8764 * The easiest way to load a problem into SCIP is via an input file, given in a format that SCIP can parse directly,
8765 * see \ref SHELL "the tutorial on how to use the interactive shell".
8766 * \SCIP is capable of reading more than ten different file formats, including formats for nonlinear
8767 * problems and constraint programs. This gives researchers from different communities an easy access to the
8768 * \SCIP Optimization Suite. See also the \ref AVAILABLEFORMATS "list of readable file formats".
8769 *
8770 * @section C_API C API
8771 *
8772 * The main access point for \SCIP is its API to C. Please refer to the \ref PUBLICAPI documentation
8773 * for further details.
8774 *
8775 * @section CPLUSPLUS C++ wrapper classes
8776 *
8777 * Since \SCIP is written in C, its callable library can be directly accessed from C++. If a user wants to program own
8778 * plugins in C++, there are wrapper classes for all different types of plugins available in the <code>src/objscip</code>
8779 * directory of the \SCIP standard distribution. SCIP provides several examples that were written in C++, see
8780 * \ref EXAMPLES "Examples".
8781 *
8782 * @section SCIPINTERFACES Interfaces for other programming languages
8783 *
8784 * Interfaces for other programming languages are developed and maintained independently from the SCIP Optimization Suite
8785 * on <a href="https://github.com/scipopt">GitHub</a> in order to provide extensions and patches faster
8786 * and to collaborate on them more easily.
8787 *
8788 * - <a href="https://github.com/scipopt/PySCIPOpt">PySCIPOpt</a> provides an extensive open-source interface for Python.
8789 * PySCIPOpt can be installed via <a href="https://anaconda.org/conda-forge/pyscipopt">conda-forge</a>,
8790 * which automatically includes \SCIP.
8791 * PySCIPOpt uses wrappers to allow users to build
8792 * their own plugins without accessing the C code of \SCIP itself.
8793 * Since Python is one of the most commonly used programming languages, especially in the field of
8794 * machine learning, the API gives easy access to the solvers functionality to incorporate \SCIP
8795 * into any python project pipeline, extract data for further analysis and computation as well as allow
8796 * customizing the solving process.
8797 * - <a href="https://github.com/scipopt/SCIP.jl">SCIP.jl</a> is a
8798 * Julia interface that exposes an API identical to the SCIP-C_API and implements the
8799 * MathOptInterface used by most constrained solvers in Julia.
8800 * It can be accessed through the Julia package manager and will install a pre-built version of
8801 * \SCIP if none is provided by the user.
8802 * - There is a <a href="https://github.com/scipopt/MatlabSCIPInterface">Matlab interface</a>
8803 * to use SCIP and SCIP-SDP from Matlab and Octave.
8804 * - <a href="https://github.com/scipopt/JSCIPOpt">JSCIPOpt</a> is an interface for Java.
8805 *
8806 * Contributions to these projects are very welcome.
8807 *
8808 * There are also several third-party python interfaces to the \SCIP Optimization Suite:
8809 * - <a href="https://github.com/eomahony/Numberjack">NUMBERJACK</a> is a constraint programming platform implemented in python.
8810 * It supports a variety of different solvers, one of them being the \SCIP Optimization Suite .
8811 * - <a href="http://code.google.com/p/python-zibopt/">python-zibopt</a> was developed
8812 * by Ryan J. O'Neil and is a python extension of the \SCIP Optimization Suite (not maintained anymore).
8813 * - <a href="http://picos.zib.de/">PICOS</a> is a python interface for conic optimization,
8814 * provided by Guillaume Sagnol.
8815 *
8816 * @section MODELLING Modeling languages
8817 *
8818 * A natural way of formulating an optimization problem is to use a modeling language.
8819 * Besides ZIMPL, which is part of the \SCIP Optimization Suite,
8820 * there are several other modeling tools with a direct interface to \SCIP:
8821 *
8822 * - <a href="https://zimpl.zib.de">ZIMPL</a>, a modeling language for constraint programming,
8823 * - both <a href="http://www.ampl.com/">AMPL</a> and <a href="http://www.gams.com">GAMS</a>,
8824 * are well-suited for modeling mixed-integer linear and nonlinear optimization problems,
8825 * - and <a href="https://projects.coin-or.org/Cmpl">CMPL</a> for mixed-integer linear problems.
8826 * - <a href="https://jump.dev/JuMP.jl/stable/">JuMP</a> accesses SCIP through the Julia interface.
8827 * - <a href="http://users.isy.liu.se/johanl/yalmip/pmwiki.php?n=Main.HomePage">YALMIP</a> by Johan L&ouml;fberg provides a
8828 * free modeling language.
8829 *
8830 * The AMPL and ZIMPL interfaces are included in the \SCIP distribution,
8831 * the GAMS interface is available <a href="https://github.com/coin-or/GAMSlinks">here</a>.
8832 *
8833 */
8834
8835 /**@defgroup PUBLICAPI Public API of SCIP
8836 * @brief methods and headers of the public C-API of \SCIP. Please refer to \ref DOC "" for information how to use the reference manual.
8837 *
8838 * \PUBLICAPIDESCRIPTION
8839 *
8840 *
8841 */
8842
8843/**@defgroup PUBLICCOREAPI Core API
8844 * @ingroup PUBLICAPI
8845 * @brief methods and headers of the plugin-independent C-API provided by the \SCIP header file scip.h.
8846 *
8847 * This module comprises methods provided by the header file scip.h. Including this header into a user-written extension
8848 * suffices to have all plugin-independent functionality of \SCIP available. Plugin-independent
8849 * user functionality includes the
8850 *
8851 * - creation of problems that \SCIP should solve
8852 * - fine-grained access to initiate the solving process of \SCIP
8853 * - access to all sorts of solving process statistics
8854 * - commonly used data structures and algorithms
8855 * - the management of plugins
8856 * - ...
8857 *
8858 * In order facilitate the navigation through the core API of \SCIP, it is structured into different modules.
8859 */
8860
8861/**@defgroup TYPEDEFINITIONS Type Definitions
8862 * @ingroup PUBLICCOREAPI
8863 * @brief type definitions and callback declarations
8864 *
8865 * This page lists headers which contain type definitions of callback methods.
8866 *
8867 * All headers below include the descriptions of callback methods of
8868 * certain plugins. For more detail see the corresponding header.
8869 */
8870
8871/**@defgroup PublicProblemMethods Problem Creation
8872 * @ingroup PUBLICCOREAPI
8873 * @brief methods to create a problem that \SCIP should solve
8874 *
8875 * This module summarizes the main methods needed to create a problem for \SCIP, and access its most important members:
8876 * - Declaring, adding, accessing, and changing variables of the problem
8877 * - Declaring, adding, accessing, and changing constraints of the problem
8878 * - Creating, adding, accessing, changing, and checking of solutions to the problem
8879 *
8880 * @note These core methods are not sufficient to create constraints of a certain type that is provided by the default plugins of \SCIP.
8881 * An example would be the creation of a linear constraint for which the methods provided by the
8882 * \ref cons_linear.h "linear constraint handler" must be used. Such methods are provided by the default plugins of \SCIP
8883 * and can be found in the \ref PUBLICPLUGINAPI.
8884 */
8885
8886/**@defgroup GeneralSCIPMethods SCIP
8887 * @ingroup PublicProblemMethods
8888 * @brief methods to manipulate a SCIP object
8889 */
8890
8891/**@defgroup GlobalProblemMethods Global Problem
8892 * @ingroup PublicProblemMethods
8893 * @brief methods to create, read and modify a global problem together with its callbacks
8894 */
8895
8896/**@defgroup PublicVariableMethods Problem Variables
8897 * @ingroup PublicProblemMethods
8898 * @brief public methods for problem variables
8899 */
8900
8901/**@defgroup PublicConstraintMethods Problem Constraints
8902 * @ingroup PublicProblemMethods
8903 * @brief Public methods for constraints
8904 */
8905
8906/**@defgroup PublicSolutionMethods Primal Solution
8907 * @ingroup PublicProblemMethods
8908 * @brief methods to create and change primal solutions of \SCIP
8909 */
8910
8911/**@defgroup CopyMethods Problem Copies
8912 * @ingroup PublicProblemMethods
8913 * @brief methods to copy problems between a source and a target \SCIP
8914 */
8915
8916
8917 /**@defgroup PublicSolveMethods Solving Process
8918 * @ingroup PUBLICCOREAPI
8919 * @brief methods to control the solving process of \SCIP
8920 *
8921 * This large group of methods and modules comprises the solving process related API of \SCIP. This includes
8922 *
8923 * -# changing parameters to control the solver behavior
8924 * -# access search tree related information
8925 * -# access relaxation information
8926 * -# access various solving process statistics
8927 * -# solve auxiliary relaxations and subproblems using LP/NLP diving or probing mode
8928 */
8929
8930/**@defgroup PublicSolvingStatsMethods Solving Statistics
8931 * @ingroup PublicSolveMethods
8932 * @brief methods to query statistics about the solving process
8933 */
8934
8935/**@defgroup ParameterMethods Parameter
8936 * @ingroup PublicSolveMethods
8937 * @brief methods to create, query, and print user parameters
8938 */
8939
8940/**@defgroup PublicEventMethods Event Handling
8941 * @ingroup PublicSolveMethods
8942 * @brief methods to create, catch, process, and drop events during the solving process of \SCIP
8943 *
8944 * Events can only be caught during the operation on the transformed problem.
8945 * Events on variables can only be caught for transformed variables.
8946 * If you want to catch an event for an original variable, you have to get the corresponding transformed variable
8947 * with a call to SCIPgetTransformedVar() and catch the event on the transformed variable.
8948 */
8949
8950/**@defgroup PublicLPMethods LP Relaxation
8951 * @ingroup PublicSolveMethods
8952 * @brief methods to build and access LP relaxation information
8953 * @see methods to interact with \ref PublicColumnMethods "LP columns" and \ref PublicRowMethods "LP rows"
8954 */
8955
8956/**@defgroup PublicColumnMethods LP Column
8957 * @ingroup PublicLPMethods
8958 * @brief public methods for LP columns
8959 */
8960
8961/**@defgroup PublicRowMethods LP Row
8962 * @ingroup PublicLPMethods
8963 * @brief public methods for LP rows
8964 */
8965
8966/**@defgroup PublicCutMethods Cuts and Cutpools
8967 * @ingroup PublicLPMethods
8968 * @brief common methods used to manipulate, generate, and strengthen cuts and to organize the cutpool
8969 */
8970
8971/**@defgroup PublicLPDivingMethods LP Diving
8972 * @ingroup PublicLPMethods
8973 * @brief methods to initiate and conduct LP diving
8974 */
8975
8976/**@defgroup PublicNLPMethods NLP Relaxation
8977 * @ingroup PublicSolveMethods
8978 * @brief methods for the nonlinear relaxation
8979 */
8980
8981/**@defgroup PublicNLRowMethods Nonlinear Rows
8982 * @ingroup PublicNLPMethods
8983 * @brief methods for the creation and interaction with rows of the NLP relaxation
8984 */
8985
8986/**@defgroup PublicNLPDiveMethods NLP Diving
8987 * @ingroup PublicNLPMethods
8988 * @brief methods to initiate and conduct NLP Diving
8989 */
8990
8991/**@defgroup PublicConflictMethods Conflict Analysis
8992 * @ingroup PublicSolveMethods
8993 * @brief public methods for conflict analysis
8994 */
8995
8996/**@defgroup PublicBranchingMethods Branching
8997 * @ingroup PublicSolveMethods
8998 * @brief methods for branching on LP solutions, relaxation solutions, and pseudo solutions
8999 *
9000 * @see \ref PublicVariableMethods "Public Variable methods" contains some typical variable branching score functions
9001 */
9002
9003/**@defgroup LocalSubproblemMethods Local Subproblem
9004 * @ingroup PublicSolveMethods
9005 * @brief methods to query information about or strengthen the problem at the current local search node
9006 */
9007
9008/**@defgroup PublicTreeMethods Search Tree
9009 * @ingroup PublicSolveMethods
9010 * @brief methods to query search tree related information
9011 * @see \ref PublicNodeMethods "Public methods for nodes"
9012 */
9013
9014/**@defgroup PublicNodeMethods Nodes
9015 * @ingroup PublicTreeMethods
9016 * @brief methods for nodes of the search tree of \SCIP
9017 */
9018
9019/**@defgroup PublicProbingMethods Probing
9020 * @ingroup PublicSolveMethods
9021 * @brief methods to initiate and control the probing mode of \SCIP
9022 */
9023
9024/**@defgroup PublicReoptimizationMethods Reoptimization
9025 * @ingroup PublicSolveMethods
9026 * @brief methods for reoptimization related tasks
9027 */
9028
9029/** @defgroup DataStructures Data Structures
9030 * @ingroup PUBLICCOREAPI
9031 * @brief commonly used data structures
9032 *
9033 * Below you find a list of available data structures
9034 */
9035
9036/** @defgroup DisjointSet Disjoint Set (Union Find)
9037 * @ingroup DataStructures
9038 * @brief weighted disjoint set (union find) data structure with path compression
9039 *
9040 * Weighted Disjoint Set is a data structure to quickly update and query connectedness information
9041 * between nodes of a graph. Disjoint Set is also known as Union Find.
9042 */
9043
9044/**@defgroup PublicDynamicArrayMethods Dynamic Arrays
9045 * @ingroup DataStructures
9046 * @brief methods for the creation and access of dynamic arrays
9047 */
9048
9049/**@defgroup DirectedGraph Directed Graph
9050 * @ingroup DataStructures
9051 * @brief graph structure with common algorithms for directed and undirected graphs
9052 */
9053
9054/**@defgroup DecompMethods Decomposition data structure
9055 * @ingroup DataStructures
9056 * @brief methods for creating and accessing user decompositions
9057 */
9058
9059/**@defgroup MiscellaneousMethods Miscellaneous Methods
9060 * @ingroup PUBLICCOREAPI
9061 * @brief commonly used methods from different categories
9062 *
9063 * Below you find a list of miscellaneous methods grouped by different categories
9064 */
9065
9066/**@defgroup PublicValidationMethods Validation
9067 * @ingroup PUBLICCOREAPI
9068 * @brief methods for validating the correctness of a solving process
9069 */
9070
9071/**@defgroup PublicMemoryMethods Memory Management
9072 * @ingroup MiscellaneousMethods
9073 * @brief methods and macros to use the \SCIP memory management
9074 *
9075 * @see \ref MEMORY "Using the memory functions of SCIP" for more information
9076 */
9077
9078/**@defgroup PublicTimingMethods Timing
9079 * @ingroup MiscellaneousMethods
9080 * @brief methods for timing
9081 */
9082
9083/**@defgroup PublicBanditMethods Bandit Algorithms
9084 * @ingroup MiscellaneousMethods
9085 * @brief methods for bandit algorithms
9086 */
9087
9088
9089
9090/**@defgroup DebugSolutionMethods Debug Solution
9091 * @ingroup PUBLICCOREAPI
9092 * @brief methods to control the SCIP debug solution mechanism, see also \ref DEBUG
9093 */
9094
9095/**@defgroup MessageOutputMethods Messaging
9096 * @ingroup PUBLICCOREAPI
9097 * @brief message output methods
9098 */
9099
9100/**@defgroup PluginManagementMethods Methods for managing plugins
9101 * @ingroup PUBLICCOREAPI
9102 * @brief Methods for the inclusion and management of SCIP plugins and callback functions
9103 *
9104 */
9105
9106/**@defgroup PublicBendersMethods Benders' decomposition
9107 * @ingroup PluginManagementMethods
9108 * @brief methods for Benders' decomposition plugins
9109 */
9110
9111/**@defgroup PublicBenderscutsMethods Benders' decomposition cuts
9112 * @ingroup PluginManagementMethods
9113 * @brief methods for Benders' decomposition cuts plugins
9114 */
9115
9116/**@defgroup PublicBranchRuleMethods Branching Rules
9117 * @ingroup PluginManagementMethods
9118 * @brief methods for branching rule plugins
9119 */
9120
9121/**@defgroup PublicCompressionMethods Tree Compression
9122 * @ingroup PluginManagementMethods
9123 * @brief public methods for tree compressions
9124 */
9125
9126/**@defgroup PublicConflicthdlrMethods Conflict Analysis
9127 * @ingroup PluginManagementMethods
9128 * @brief public methods for conflict handlers
9129 */
9130
9131/**@defgroup PublicConshdlrMethods Constraint handlers
9132 * @ingroup PluginManagementMethods
9133 * @brief methods for constraint handlers
9134 */
9135
9136/**@defgroup PublicCutSelectorMethods Cut Selector
9137 * @ingroup PluginManagementMethods
9138 * @brief methods for cut selectors
9139 */
9140
9141/**@defgroup PublicDialogMethods Dialogs
9142 * @ingroup PluginManagementMethods
9143 * @brief public methods for user interface dialogs
9144 */
9145
9146/**@defgroup PublicDisplayMethods Displays
9147 * @ingroup PluginManagementMethods
9148 * @brief methods for the inclusion and access of display plugins
9149 */
9150
9151/**@defgroup PublicEventHandlerMethods Event Handler
9152 * @ingroup PluginManagementMethods
9153 * @brief methods for event handlers
9154 */
9155
9156/**@defgroup PublicExprHandlerMethods Expression Handler
9157 * @ingroup PluginManagementMethods
9158 * @brief methods for expression handlers
9159 */
9160
9161/**@defgroup PublicHeuristicMethods Primal Heuristics
9162 * @ingroup PluginManagementMethods
9163 * @brief methods for primal heuristic plugins
9164 */
9165
9166/**@defgroup PublicDivesetMethods Dive sets
9167 * @ingroup PublicSpecialHeuristicMethods
9168 * @brief methods for dive sets to control the generic diving algorithm
9169 */
9170
9171/**@defgroup PublicNodeSelectorMethods Node Selector
9172 * @ingroup PluginManagementMethods
9173 * @brief methods for node selector plugin management
9174 */
9175
9176/**@defgroup PublicNlhdlrInterfaceMethods Nonlinear Handlers
9177 * @ingroup PluginManagementMethods
9178 * @brief methods for the management of nonlinear handlers
9179 */
9180
9181/**@defgroup PublicPresolverMethods Presolver
9182 * @ingroup PluginManagementMethods
9183 * @brief methods for presolver plugins
9184 */
9185
9186/**@defgroup PublicPricerMethods Pricer
9187 * @ingroup PluginManagementMethods
9188 * @brief methods to include and access pricer plugins of \SCIP
9189 */
9190
9191/**@defgroup PublicPropagatorMethods Propagators
9192 * @ingroup PluginManagementMethods
9193 * @brief methods for propagator plugins
9194 */
9195
9196/**@defgroup PublicReaderMethods Reader
9197 * @ingroup PluginManagementMethods
9198 * @brief methods for the inclusion and access to reader plugins of \SCIP
9199 */
9200
9201/**@defgroup PublicRelaxatorMethods Relaxation Handlers
9202 * @ingroup PluginManagementMethods
9203 * @brief public methods for relaxation handlers
9204 */
9205
9206/**@defgroup PublicSeparatorMethods Separators
9207 * @ingroup PluginManagementMethods
9208 * @brief methods for separator plugins
9209 */
9210
9211/**@defgroup PublicTableMethods Tables
9212 * @ingroup PluginManagementMethods
9213 * @brief methods for the inclusion and access of statistics tables
9214 */
9215
9216/**@defgroup PublicConcsolverTypeMethods Concurrent Solver Types
9217 * @ingroup PluginManagementMethods
9218 * @brief methods for concurrent solver type plugins
9219 */
9220
9221/**@defgroup PublicNLPIInterfaceMethods NLP solver interfaces
9222 * @ingroup PluginManagementMethods
9223 * @brief methods for the management of NLP solver interfaces
9224 */
9225
9226/**@defgroup PublicExternalCodeMethods External Codes
9227 * @ingroup PluginManagementMethods
9228 * @brief methods to access information about external codes used by \SCIP
9229 */
9230
9231/**@defgroup PublicParallelMethods Parallel Interface
9232 * @ingroup PUBLICCOREAPI
9233 * @brief methods to construct the parallel interface of \SCIP
9234 */
9235
9236 /**@defgroup PUBLICPLUGINAPI Plugin API of SCIP
9237 * @ingroup PUBLICAPI
9238 * @brief core API extensions provided by the default plugins of \SCIP, includable via scipdefplugins.h.
9239 *
9240 * All default plugins of \SCIP, especially the default \ref CONSHDLRS "constraint handlers", provide
9241 * valuable extensions to the \ref PUBLICCOREAPI "core API" of \SCIP. These methods are made available
9242 * by including scipdefplugins.h to user-written extensions.
9243 *
9244 * For a better overview, this page lists all default plugin headers structured into modules based on their individual
9245 * topic.
9246 *
9247 * All of the modules listed below provide functions that are allowed to be used by user-written extensions of \SCIP.
9248 */
9249 /**@defgroup INTERNALAPI Internal API of SCIP
9250 * @brief internal API methods that should only be used by the core of \SCIP
9251 *
9252 * This page lists the header files of internal API methods. In contrast to the public API, these internal methods
9253 * should not be used by user plugins and extensions of SCIP. Please consult
9254 * \ref PUBLICCOREAPI "the Core API" and \ref PUBLICPLUGINAPI "Plugin API" for the complete API available to user plugins.
9255 *
9256 */
9257
9258/**@defgroup BENDERS Benders' decomposition implementations
9259 * @ingroup PUBLICPLUGINAPI
9260 * @brief methods and files provided by the default Benders' decomposition implementations of \SCIP
9261 *
9262 * A detailed description what a Benders' decomposition implementation does and how to add a Benders' decomposition
9263 * implementations to SCIP can be found
9264 * \ref BENDER "here".
9265 */
9266
9267/**@defgroup BendersIncludes Inclusion methods
9268 * @ingroup BENDERS
9269 * @brief methods to include specific Benders' decomposition implementations into \SCIP
9270 *
9271 * This module contains methods to include specific Benders' decomposition implementations into \SCIP.
9272 *
9273 * @note All default plugins can be included at once (including all Benders' decomposition implementations) using
9274 * SCIPincludeDefaultPlugins()
9275 *
9276 */
9277
9278/**@defgroup BENDERSCUTS Benders' decomposition cut method
9279 * @ingroup PUBLICPLUGINAPI
9280 * @brief methods and files provided by the default Benders' decomposition cut method of \SCIP
9281 *
9282 * A detailed description what a Benders' decomposition cut method does and how to add a Benders' decomposition
9283 * cut method to SCIP can be found
9284 * \ref BENDERSCUT "here".
9285 */
9286
9287/**@defgroup BenderscutIncludes Inclusion methods
9288 * @ingroup BENDERSCUTS
9289 * @brief methods to include specific Benders' decomposition cut methods into \SCIP
9290 *
9291 * This module contains methods to include specific Benders' decomposition cut methods into \SCIP.
9292 *
9293 * @note The Benders' decomposition cut methods are linked to each Benders' decomposition implementation. Thus, the
9294 * default Benders' decomposition implementations automatically include the necessary Benders' decomposition cut
9295 * methods. For custom Benders' decomposition implementations, you can call SCIPincludeDefaultBendersCuts() in the
9296 * SCIPincludeBendersMybenders() include function.
9297 *
9298 */
9299
9300/**@defgroup BRANCHINGRULES Branching Rules
9301 * @ingroup PUBLICPLUGINAPI
9302 * @brief methods and files provided by the default branching rules of \SCIP
9303 *
9304 * A detailed description what a branching rule does and how to add a branching rule to SCIP can be found
9305 * \ref BRANCH "here".
9306 */
9307
9308/**@defgroup BranchingRuleIncludes Inclusion methods
9309 * @ingroup BRANCHINGRULES
9310 * @brief methods to include specific branching rules into \SCIP
9311 *
9312 * This module contains methods to include specific branching rules into \SCIP.
9313 *
9314 * @note All default plugins can be included at once (including all branching rules) using SCIPincludeDefaultPlugins()
9315 *
9316 */
9317
9318/**@defgroup CONSHDLRS Constraint Handlers
9319 * @ingroup PUBLICPLUGINAPI
9320 * @brief methods and files provided by the default constraint handlers of \SCIP
9321 *
9322 * A detailed description what a constraint handler does and how to add a constraint handler to SCIP can be found
9323 * \ref CONS "here".
9324 */
9325
9326/**@defgroup ConshdlrIncludes Inclusion methods
9327 * @ingroup CONSHDLRS
9328 * @brief methods to include specific constraint handlers into \SCIP
9329 *
9330 * This module contains methods to include specific constraint handlers into \SCIP.
9331 *
9332 * @note All default plugins can be included at once (including all default constraint handlers) using SCIPincludeDefaultPlugins()
9333 *
9334 */
9335
9336/**@defgroup CUTSELECTORS Cut Selectors
9337 * @ingroup PUBLICPLUGINAPI
9338 * @brief methods and files provided by the default cut selectors of \SCIP
9339 *
9340 * A detailed description what a cut selector does and how to add a cut selector to SCIP can be found
9341 * \ref CUTSEL "here".
9342 */
9343
9344/**@defgroup CutSelectorIncludes Inclusion methods
9345 * @ingroup CUTSELECTORS
9346 * @brief methods to include specific cut selectors into \SCIP
9347 *
9348 * This module contains methods to include specific cut selectors into \SCIP.
9349 *
9350 * @note All default plugins can be included at once (including all default cut selectors) using SCIPincludeDefaultPlugins()
9351 *
9352 */
9353
9354/**@defgroup DIALOGS Dialogs
9355 * @ingroup PUBLICPLUGINAPI
9356 * @brief methods and files provided by the default dialogs of \SCIP
9357 *
9358 * A detailed description what a dialog does and how to add a dialog to SCIP can be found
9359 * \ref DIALOG "here".
9360 */
9361
9362/**@defgroup DialogIncludes Inclusion methods
9363 * @ingroup DIALOGS
9364 * @brief methods to include specific dialogs into \SCIP
9365 *
9366 * This module contains methods to include specific dialogs into \SCIP.
9367 *
9368 * @note All default plugins can be included at once (including all default dialogs) using SCIPincludeDefaultPlugins()
9369 *
9370 */
9371
9372/**@defgroup DISPLAYS Displays
9373 * @ingroup PUBLICPLUGINAPI
9374 * @brief methods and files provided by the default displays (output columns) of \SCIP
9375 *
9376 * A detailed description what a display does and how to add a display to SCIP can be found
9377 * \ref DISP "here".
9378 *
9379 */
9380
9381/**@defgroup DisplayIncludes Inclusion methods
9382 * @ingroup DISPLAYS
9383 * @brief methods to include specific displays into \SCIP
9384 *
9385 * This module contains methods to include specific displays into \SCIP.
9386 *
9387 * @note All default plugins can be included at once (including all default displays) using SCIPincludeDefaultPlugins()
9388 *
9389 */
9390
9391/**@defgroup EXPRHDLRS Expression Handlers
9392 * @ingroup PUBLICPLUGINAPI
9393 * @brief methods and files provided by the default expressions handlers of \SCIP
9394 */
9395
9396/**@defgroup ExprhdlrIncludes Inclusion methods
9397 * @ingroup EXPRHDLRS
9398 * @brief methods to include specific expression handlers into \SCIP
9399 *
9400 * This module contains methods to include specific expression handlers into \SCIP.
9401 *
9402 * @note All default plugins can be included at once (including all default expression handlers) using SCIPincludeDefaultPlugins()
9403 *
9404 */
9405
9406/**@defgroup EXPRINTS Expression Interpreter
9407 * @ingroup PUBLICPLUGINAPI
9408 * @brief methods and files provided by the default expression interpreters of \SCIP
9409 *
9410 * A detailed description what a expression interpreter does and how to add a expression interpreter to SCIP can be found
9411 * \ref EXPRINT "here".
9412 */
9413
9414/**@defgroup FILEREADERS File Readers
9415 * @ingroup PUBLICPLUGINAPI
9416 * @brief This page contains a list of all file readers which are currently available.
9417 *
9418 * @section AVAILABLEFORMATS List of readable file formats
9419 *
9420 * The \ref SHELL "interactive shell" and the callable library are capable of reading/parsing several different file
9421 * formats.
9422 *
9423 * <table>
9424 * <tr><td>\ref reader_bnd.h "BND format"</td> <td>for variable bounds</td></tr>
9425 * <tr><td>\ref reader_cip.h "CIP format"</td> <td>for SCIP's constraint integer programming format</td></tr>
9426 * <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>
9427 * <tr><td>\ref reader_diff.h "DIFF format"</td> <td>for reading a new objective function for mixed-integer programs</td></tr>
9428 * <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>
9429 * <tr><td>\ref reader_lp.h "LP format"</td> <td>for mixed-integer (quadratically constrained quadratic) programs (CPLEX)</td></tr>
9430 * <tr><td>\ref reader_mps.h "MPS format"</td> <td>for mixed-integer (quadratically constrained quadratic) programs</td></tr>
9431 * <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
9432 * <tr><td>\ref reader_opb.h "OPB format"</td> <td>for pseudo-Boolean optimization instances</td></tr>
9433 * <tr><td>\ref reader_osil.h "OSiL format"</td> <td>for mixed-integer nonlinear programs</td></tr>
9434 * <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>
9435 * <tr><td>\ref reader_sol.h "SOL format"</td> <td>for solutions; XML-format (read-only) or raw SCIP format</td></tr>
9436 * <tr><td>\ref reader_wbo.h "WBO format"</td> <td>for weighted pseudo-Boolean optimization instances</td></tr>
9437 * <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
9438 * programming problems [read only]</td></tr>
9439 * </table>
9440 *
9441 * @section ADDREADER How to add a file reader
9442 *
9443 * A detailed description what a file reader does and how to add a file reader to SCIP can be found
9444 * \ref READER "here".
9445 *
9446 */
9447
9448/**@defgroup FileReaderIncludes Inclusion methods
9449 * @ingroup FILEREADERS
9450 * @brief methods to include specific file readers into \SCIP
9451 *
9452 * This module contains methods to include specific file readers into \SCIP.
9453 *
9454 * @note All default plugins can be included at once (including all default file readers) using SCIPincludeDefaultPlugins()
9455 *
9456 */
9457
9458/**@defgroup PARALLEL Parallel interface methods
9459 * @ingroup INTERNALAPI
9460 * @brief headers and methods for the parallel interface of \SCIP
9461 *
9462 */
9463
9464/**@defgroup PublicSymmetryMethods Symmetry
9465 * @ingroup INTERNALAPI
9466 * @brief methods for symmetry handling
9467 */
9468
9469/**@defgroup FileReaderIncludes Inclusion methods
9470 * @ingroup FILEREADERS
9471 * @brief methods to include specific file readers into \SCIP
9472 *
9473 * This module contains methods to include specific file readers into \SCIP.
9474 *
9475 * @note All default plugins can be included at once (including all default file readers) using SCIPincludeDefaultPlugins()
9476 *
9477 */
9478
9479/**@defgroup LPIS LP Solver Interface
9480 * @ingroup PUBLICPLUGINLPI
9481 * @brief methods and files provided by the LP solver interface of \SCIP
9482 *
9483 * \SCIP uses external tools to solve LP relaxations. The communication
9484 * is realized through an LP interface.
9485 *
9486 * This page lists public interface methods that every LP interface provides.
9487 * Find the concrete implementation for your LP solver
9488 * under "src/lpi/".
9489 *
9490 * @see \ref LPI for a list of available LP solver interfaces
9491 */
9492
9493/**@defgroup NODESELECTORS Node Selectors
9494 * @ingroup PUBLICPLUGINAPI
9495 * @brief methods and files provided by the default node selectors of \SCIP
9496 *
9497 * A detailed description what a node selector does and how to add a node selector to SCIP can be found
9498 * \ref NODESEL "here".
9499 */
9500
9501/**@defgroup NodeSelectorIncludes Inclusion methods
9502 * @ingroup NODESELECTORS
9503 * @brief methods to include specific node selectors into \SCIP
9504 *
9505 * This module contains methods to include specific node selectors into \SCIP.
9506 *
9507 * @note All default plugins can be included at once (including all default node selectors) using SCIPincludeDefaultPlugins()
9508 *
9509 */
9510
9511/**@defgroup NLHDLRS Nonlinear Handlers
9512 * @ingroup PUBLICPLUGINAPI
9513 * @brief methods and files provided by the default nonlinear handlers of \SCIP
9514 */
9515
9516/**@defgroup NlhdlrIncludes Inclusion methods
9517 * @ingroup NLHDLRS
9518 * @brief methods to include specific nonlinear handlers into \SCIP
9519 *
9520 * This module contains methods to include specific nonlinear handlers into \SCIP.
9521 *
9522 * @note All default plugins can be included at once (including all default nonlinear handlers) using SCIPincludeDefaultPlugins()
9523 *
9524 */
9525
9526/**@defgroup NLPIS NLP Solver Interfaces
9527 * @ingroup PUBLICPLUGINAPI
9528 * @brief methods and files provided by the default NLP solver interfaces of \SCIP
9529 *
9530 * A detailed description what a NLP solver interface does and how to add a NLP solver interface to SCIP can be found
9531 * \ref NLPI "here".
9532 */
9533
9534/**@defgroup NLPIIncludes Inclusion methods
9535 * @ingroup NLPIS
9536 * @brief methods to include specific NLP solver interfaces into \SCIP
9537 *
9538 * This module contains methods to include specific NLP solver interfaces into \SCIP.
9539 *
9540 * @note All default plugins can be included at once (including all default NLP solver interfaces) using SCIPincludeDefaultPlugins()
9541 *
9542 */
9543
9544/**@defgroup PRESOLVERS Presolvers
9545 * @ingroup PUBLICPLUGINAPI
9546 * @brief methods and files provided by the default presolvers of \SCIP
9547 *
9548 * A detailed description what a presolver does and how to add a presolver to SCIP can be found
9549 * \ref PRESOL "here".
9550 */
9551
9552/**@defgroup PresolverIncludes Inclusion methods
9553 * @ingroup PRESOLVERS
9554 * @brief methods to include specific presolvers into \SCIP
9555 *
9556 * This module contains methods to include specific presolvers into \SCIP.
9557 *
9558 * @note All default plugins can be included at once (including all default presolvers) using SCIPincludeDefaultPlugins()
9559 *
9560 */
9561
9562/**@defgroup PRICERS Pricers
9563 * @ingroup PUBLICPLUGINAPI
9564 * @brief methods and files provided by the default pricers of \SCIP
9565 *
9566 * Per default there exist no variable pricer. A detailed description what a variable pricer does and how to add a
9567 * variable pricer to SCIP can be found \ref PRICER "here".
9568 */
9569
9570/**@defgroup PricerIncludes Inclusion methods
9571* @ingroup PRICERS
9572* @brief methods to include specific pricers into \SCIP
9573*
9574* This module contains methods to include specific pricers into \SCIP.
9575*
9576* @note All default plugins can be included at once using SCIPincludeDefaultPlugins(). There exists no pricer per default.
9577* In order to see examples of variable pricers, please consult the \ref EXAMPLES "Coding Examples" of \SCIP.
9578*
9579*/
9580
9581/**@defgroup PRIMALHEURISTICS Primal Heuristics
9582 * @ingroup PUBLICPLUGINAPI
9583 * @brief methods and files provided by the default primal heuristics of \SCIP
9584 *
9585 * A detailed description what a primal heuristic does and how to add a primal heuristic to SCIP can be found
9586 * \ref HEUR "here".
9587 */
9588
9589/**@defgroup PrimalHeuristicIncludes Inclusion methods
9590 * @ingroup PRIMALHEURISTICS
9591 * @brief methods to include specific primal heuristics into \SCIP
9592 *
9593 * This module contains methods to include specific primal heuristics into \SCIP.
9594 *
9595 * @note All default plugins can be included at once (including all default primal heuristics) using SCIPincludeDefaultPlugins()
9596 *
9597 */
9598
9599/**@defgroup PROPAGATORS Propagators
9600 * @ingroup PUBLICPLUGINAPI
9601 * @brief methods and files provided by the default propagators of \SCIP
9602 *
9603 * A detailed description what a propagator does and how to add a propagator to SCIP can be found
9604 * \ref PROP "here".
9605 */
9606
9607/**@defgroup PropagatorIncludes Inclusion methods
9608 * @ingroup PROPAGATORS
9609 * @brief methods to include specific propagators into \SCIP
9610 *
9611 * This module contains methods to include specific propagators into \SCIP.
9612 *
9613 * @note All default plugins can be included at once (including all default propagators) using SCIPincludeDefaultPlugins()
9614 *
9615 */
9616
9617/**@defgroup RELAXATORS Relaxation Handlers
9618 * @ingroup PUBLICPLUGINAPI
9619 * @brief methods and files provided by the default relaxation handlers of \SCIP
9620 *
9621 * A detailed description what a relaxation handler does and how to add a relaxation handler to SCIP can be found
9622 * \ref RELAX "here". Note that the linear programming relaxation is not implemented via the relaxation handler plugin.
9623 * Per default no relaxation handler exists in SCIP. However, there are two relaxation handlers in the
9624 * \ref RELAXATOR_MAIN "Relaxator example".
9625 */
9626
9627/**@defgroup SEPARATORS Separators
9628 * @ingroup PUBLICPLUGINAPI
9629 * @brief methods and files provided by the default separators of \SCIP
9630 *
9631 * A detailed description what a separator does and how to add a separator to SCIP can be found
9632 * \ref SEPA "here".
9633 */
9634
9635/**@defgroup SeparatorIncludes Inclusion methods
9636 * @ingroup SEPARATORS
9637 * @brief methods to include specific separators into \SCIP
9638 *
9639 * This module contains methods to include specific separators into \SCIP.
9640 *
9641 * @note All default plugins can be included at once (including all default separators) using SCIPincludeDefaultPlugins()
9642 *
9643 */
9644
9645/**@defgroup TABLES Tables
9646 * @ingroup PUBLICPLUGINAPI
9647 * @brief methods and files provided by the default statistics tables of \SCIP
9648 *
9649 * A detailed description what a table does and how to add a table to SCIP can be found
9650 * \ref TABLE "here".
9651 *
9652 */
9653
9654/**@defgroup TableIncludes Inclusion methods
9655 * @ingroup TABLES
9656 * @brief methods to include specific tables into \SCIP
9657 *
9658 * This module contains methods to include specific statistics tables into \SCIP.
9659 *
9660 * @note All default plugins can be included at once (including all default statisticstables) using SCIPincludeDefaultPlugins()
9661 *
9662 */
9663
9664/**@defgroup PublicToleranceMethods Computations With Tolerances
9665 * @ingroup NumericalMethods
9666 * @brief methods used by the majority of operations involving floating-point computations in \SCIP
9667 *
9668 * - query the numerical tolerances of \SCIP, as well as special values such as infinity.
9669 * - change tolerances inside relaxations
9670 * - epsilon-comparison methods for floating point numbers
9671 */
9672
9673/** @defgroup CFILES Implementation files (.c files)
9674 * @brief implementation files (.c files) of the SCIP core and the default plugins
9675 *
9676 * The core provides the functionality for creating problems, variables, and general constraints.
9677 * The default plugins of SCIP provide a mix of public API function and private, static function and callback declarations.
9678 */
9679
9680/** @defgroup DEFPLUGINS SCIP Default Plugins
9681 * @ingroup CFILES
9682 * @brief implementation files (.c files) of the SCIP default plugins
9683 *
9684 * The SCIP default plugins provide a mix of public API function and private, static function and callback declarations.
9685 */
9686
9687/** @defgroup OTHER_CFILES Other implementation files of SCIP
9688 * @ingroup CFILES
9689 * @brief other implementation files of SCIP
9690 *
9691 * Relevant core and other functionality of SCIP.
9692 */