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-2023 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 8.1.0
108 *
109 * \image html scippy.png
110 */
111
112/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
113
114/** @page LPI Available implementations of the LP solver interface
115 *
116 * SCIP provides a range of different interfaces to LP solvers:
117 *
118 * LPI name | LP solver
119 * ---------|----------
120 * `spx` | SoPlex
121 * `cpx` | IBM ILOG CPLEX
122 * `xprs` | FICO XPress
123 * `grb` | Gurobi (version at least 7.0.2 required)
124 * `clp` | CoinOR CLP (interface currently sometimes produces wrong results)
125 * `glop` | Google Glop (contained in OR-tools)
126 * `msk` | Mosek (version at least 7.0.0 required)
127 * `qsopt` | QSopt (experimental)
128 * `none` | disables LP solving entirely (not recommended; only for technical reasons)
129 *
130 * There are two different interfaces for SoPlex. The default one (`spx`) uses an updated interface that is provided
131 * by SoPlex itself (since version 2.0), resulting in a slimmer LPI that is similiar to those for CPLEX or XPRESS.
132 * The other one - `spx1` - is the older LPI that directly interfaces the internal simplex solver of SoPlex and
133 * therefore needs to duplicate some features in the LPI that are already available in SoPlex itself. It lacks some
134 * features like persistent scaling which are only available in the modern interface. Upcoming features may not be
135 * supported. Old compilers might have difficulties with the new interface because some C++11 features are required
136 * that may not be supported.
137 *
138 */
139
140/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
141
142/** @page NLPISOLVERS Available implementations of the NLP solver interface
143 *
144 * SCIP implements the NLP solver interface for the solvers <a href="https://github.com/coin-or/Ipopt">IPOPT</a>, <a
145 * href="https://worhp.de/">WORHP</a>, and <a href="http://www.mcs.anl.gov/~leyffer/solvers.html">FilterSQP</a>. In
146 * contrast to the implementations of the LP solver interface, SCIP can be compiled with multiple NLP solvers and selects
147 * the solver with the highest priority at the beginning of the solving process.
148 * Currently, the priorities are, in descending order: Ipopt, WORHP/IP, FilterSQP, WORHP/SQP.
149 *
150 * If more than one solver is available, then it is possible to solve all NLPs during the solving process with all
151 * available NLP solvers by setting the parameter `nlpi/all/priority` to the highest value.
152 * In this case, SCIP uses the solution from a solver that provides the best objective value. Other possible use
153 * cases for the availability of multiple solvers have not been implemented yet.
154 *
155 * In the @ref MAKE "GNU make" based build system, building the implementations of the interface for FilterSQP, IPOPT, and
156 * WORHP can be enabled by specifying `FILTERSQP=true`, `IPOPT=true`, and `WORHP=true`, respectively, as argument to the
157 * `make` call.
158 * In the @ref CMAKE "CMAKE" based build system, building the implementation of the interface for IPOPT and WORHP can be
159 * enabled by specifying `IPOPT=on` and `WORHP=on`, respectively, as argument to the `cmake` call.
160 *
161 * @section NLPISOLVERS_IPOPT IPOPT
162 *
163 * <b>IPOPT</b> implements a primal-dual interior point method and uses line searches based on filter methods. It has
164 * been developed by Andreas W&auml;chter and Carl Laird and is available under the Eclipse Public License on <a
165 * href="https://www.coin-or.org/">COIN-OR</a>.
166 *
167 * @section NLPISOLVERS_WORHP WORHP
168 *
169 * <b>WORHP</b> implements a sequential quadratic programming method and a penalty-interior point algorithm. It is
170 * developed at the <a href="https://www.uni-bremen.de/en/">University of Bremen</a> and is free for academic
171 * purposes.
172 *
173 * @section NLPISOLVERS_FILTERSQP FilterSQP
174 *
175 * <b>FilterSQP</b> implements a sequential quadratic programming method. It has been developed by Roger Fletcher
176 * and Sven Leyffer. It is not publicly available, but may be obtained from Sven Leyffer on request.
177 */
178
179/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
180
181/**@page GETTINGSTARTED First Steps Walkthrough
182 *
183 * @section GETTINGSTARTED_BLACKBOX Use SCIP to solve a problem
184 *
185 * @subsection GETTINGSTARTED_BLACKBOX_WHY Why SCIP?
186 *
187 * Charlotte lectures at a university and she wants her students to get in touch with solving constraint integer programs (CIPs).
188 * She would like to use SCIP for this purpose because it allows the students to look at the full source code
189 * and SCIP comes with a permissive open source \ref LICENSE "license".
190 * Also, her advisor told her that there are various \ref INTERFACES "interfaces" to SCIP.
191 *
192 * @subsection GETTINGSTARTED_BLACKBOX_PROBLEMS What Kinds Of Problems?
193 *
194 * As a first step she checks \ref WHATPROBLEMS "what types of problems" \SCIP can solve and
195 * \ref FILEREADERS "what are readable formats", and is happy to find MIPs to be among them.
196 *
197 * @subsection GETTINGSTARTED_BLACKBOX_INSTALL Setup
198 *
199 * Charlotte now needs to \ref INSTALL "install SCIP".
200 * She works on a recent computer with a windows system and already has the <a href="https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads">Visual C++ Redistributable Packages</a> and <a href="https://github.com/oneapi-src/oneTBB">TBB</a> installed.
201 *
202 * Having these prerequisites in place, Charlotte downloads the 64-bit windows exectuable from the <a href="https://scipopt.org/index.php#download">download page</a> and installs it without a problem.
203 * They also read about the <a href="http://www.pokutta.com/blog/pages/scip/scip-teaching.html"> dockerized SCIP container</a> which she wants
204 * to recommend to her students, in case they are unable to install SCIP on their own machines.
205 *
206 * @subsection GETTINGSTARTED_BLACKBOX_SOLVE Solve A First Problem
207 *
208 * To test her installation and get a first feeling for SCIP, Charlotte follows the steps described in the \ref QUICKSTART "quickstart" section to solve a first simple lp problem.
209 *
210 * She has just solved a problem, using SCIP in the command-based mode, by passing a command to the scip call via the `-c` flag.
211 * These commands can also be typed into the interactive shell, that one uses by just calling the binary `scip`.
212 *
213 * After the first solution process worked like a charm, Charlotte downloads a more complicated problem file from the <a href="https://miplib.zib.de/instance_details_enlight_hard.html">MIPLIB 2017</a> page
214 * and follows the \ref SHELL_AFTERINSTALL "interactive shell tutorial".
215 * There, she already learns quite a lot about the solving process and how to work with the interactive shell.
216 *
217 * @subsection GETTINGSTARTED_BLACKBOX_HELP Getting Help
218 *
219 * Feeling happy about having already solved some instances and having worked in interactive mode, Charlotte is curious on what more options SCIP has.
220 * She types `scip -h` to find out.
221 *
222 * She feels confident to being able to understand and use some of the other options, like `-l` to write the output to a logfile, or `-b` to pass a file containing the commands to be executed by scip.
223 * There are some commands that do not yet make a lot of sense to her, but she doesn't worry about it for now.
224 * She will familiarize herself with it over time and with experience.
225 *
226 * @section GETTINGSTARTED_DEVELOP Develop A Custom Plugin
227 *
228 * Alex is a researcher in Charlotte's group and is working on problems that have a very special structure that he hopes to be able to exploit in the solving process.
229 *
230 * Alex heard Charlotte talk about SCIP.
231 * She explained that SCIP is plugin-based, that is, different components (plugins) are implemented using a generic interface and that it is very easy to write your own plugins, like constraint handlers, heuristics etc.
232 * So Alex decides to give it a go and dive into SCIP.
233 *
234 * @subsection GETTINGSTARTED_DEVELOP_PREREQUISITES Prerequisites And Setup
235 *
236 * After some time of using SCIP, he feels confident enough to dig into the source code and decides to write his own plugin.
237 * Alex likes to use his linux machine for developing code, because in his experience compilation is easiest there.
238 *
239 * He starts by downloading the latest <a href="http://scipopt.org/#download">source code tarball</a>,
240 * unpacking it and compiling via \ref CMAKE "cmake", typing `mkdir build; cd build; cmake ..; make`.
241 *
242 * @subsection GETTINGSTARTED_DEVELOP_HELP Getting help
243 *
244 * Before writing any code, he quickly scans over the contents of the \ref PROGRAMMING "Programming with SCIP" page,
245 * so that he knows about some of the pitfalls, best practices and mechanisms.
246 * If a problem comes up later or he gets stuck, he knows what to look out for and where to find help.
247 *
248 * Whenever Alex gets stuck inside the code, he makes use of the extensive documentation to \ref DOC "search for interface methods".
249 *
250 * @subsection GETTINGSTARTED_DEVELOP_EXAMPLE Writing An Example
251 *
252 * Alex is now ready to write his very first example, he creates a new folder `MinEx` under `examples` and puts two files in there:
253 * `CMakeLists.txt`:
254 * ```
255 * cmake_minimum_required(VERSION 3.3)
256 *
257 * project(minex)
258 * find_package(SCIP REQUIRED)
259 * include_directories(${SCIP_INCLUDE_DIRS})
260 *
261 * add_executable(minex
262 * src/cmain.c)
263 *
264 * target_link_libraries(minex ${SCIP_LIBRARIES})
265 *
266 * if( TARGET examples )
267 * add_dependencies( examples minex )
268 * endif()
269 * ```
270 *
271 * and `cmain.c` in a subfolder `src`:
272 * ```
273 * #include <string.h>
274 * #include <scip/scip.h>
275 *
276 * int main( int argc, char** argv )
277 * {
278 * SCIP* scip = NULL;
279 * SCIP_CALL( SCIPcreate(&scip) ); // initialize SCIP
280 * SCIPinfoMessage(scip, NULL, "Hello world.\n"); // output greeting
281 * SCIP_CALL( SCIPfree(&scip) ); // free SCIP
282 * BMScheckEmptyMemory();
283 * return 0;
284 * }
285 * ```
286 *
287 * This is a minimal example that just prints "Hello world." and exits.
288 * Alex compiles and runs it via cmake with the following command:
289 * ```
290 * mkdir build; cd build; cmake .. -DSCIP_DIR=../../build/; make; ./minex
291 * ```
292 *
293 * After having successfully written this minimal example, Alex follows the instructions to \ref START "start a new project" to start his actual project and extend this most basic code.
294 *
295 * @subsection GETTINGSTARTED_DEVELOP_CONSTRAINTHANDLER Writing A Plugin
296 *
297 * Alex now needs a custom constraint handler in his project, for that he will write a custom plugin.
298 * He looks up the instructions in the \ref HOWTOADD "How to add..." page and is
299 * very happy to find \ref CONS "a page with a detailed description" what he has to do.
300 *
301 * Furthermore he found exercises for implementing plugins for the example of the
302 * linear ordering problem. The corresponding code framework
303 * (<a href="https://scipopt.org/workshop2018/pyscipopt-exercises.tgz">Python</a> or
304 * <a href="https://scipopt.org/workshop2018/exercise.pdf">C/C++</a>)
305 * could form a good starting point for a new project as well.
306 *
307 * @subsection GETTINGSTARTED_DEVELOP_REOPTMIZATION Using Functionality In A Plugin
308 *
309 * After implementing his own constraint handler Alex realizes that he needs to use repotimization in his project.
310 * He looks up the \ref HOWTOUSESECTION "How to use..." section and finds some more information about \ref REOPT "how to use reoptimization".
311 *
312 */
313
314/**@page INSTALL Installing SCIP
315 *
316 * There are two options to get a running SCIP on your system.
317 * You can either use one of the installers or you can compile it yourself.
318 *
319 * Which one you choose depends on your use case and your level of expertise.
320 * If you just want to use SCIP as a black box solver you should use an installer with a precompiled binary from the <a href="http://scipopt.org/#download">download section</a>.
321 * This is highly recommended for new users.
322 * If you are just curious and want to try it out you can use the <a href="http://www.pokutta.com/blog/pages/scip/scip-teaching.html"> dockerized SCIP container</a>.
323 *
324 * However, if you want to develop your own plugin for SCIP, you have to compile SCIP or the SCIPOptSuite from source code, which are available as a tarball from the <a href="http://scipopt.org/#download">download page</a>.
325 * Note that you might need some level of experience to be able to do this, this is described in the following.
326 *
327 * SCIP lets you choose freely between its own, manually maintained Makefile system
328 * or the CMake cross platform build system generator. For new users, we strongly
329 * recommend to use CMake, if available on their targeted platform.
330 *
331 * Be aware that generated libraries and binaries of both systems might be different and incompatible.
332 *
333 * - @subpage md_INSTALL "Installation instructions"
334 * - @subpage LPI "Available implementations of the LP solver interface"
335 * - @subpage NLPISOLVERS "Available implementations of the NLP solver interface"
336 * - @subpage INSTALL_APPLICATIONS_EXAMPLES "Installation of applications and examples"
337 */
338
339/**@page PROGRAMMING Programming with SCIP
340 *
341 * - @subpage CODE "Coding style guidelines"
342 * - @subpage OBJ "Creating, capturing, releasing, and adding data objects"
343 * - @subpage MEMORY "Using the memory functions of SCIP"
344 * - @subpage DEBUG "Debugging"
345 */
346/**@page HOWTOADD How to add ...
347 *
348 * Below you find for most plugin types a detailed description of how to implement and add them to \SCIP.
349 *
350 * - @subpage CONS "Constraint handlers"
351 * - @subpage PRICER "Variable pricers"
352 * - @subpage PRESOL "Presolvers"
353 * - @subpage SEPA "Separators"
354 * - @subpage PROP "Propagators"
355 * - @subpage BRANCH "Branching rules"
356 * - @subpage CUTSEL "Cut selectors"
357 * - @subpage NODESEL "Node selectors"
358 * - @subpage HEUR "Primal heuristics"
359 * - @subpage DIVINGHEUR "Diving heuristics"
360 * - @subpage RELAX "Relaxation handlers"
361 * - @subpage READER "File readers"
362 * - @subpage DIALOG "Dialogs"
363 * - @subpage DISP "Display columns"
364 * - @subpage EVENT "Event handler"
365 * - @subpage EXPRHDLR "Expression handlers"
366 * - @subpage NLHDLR "Nonlinear handlers"
367 * - @subpage NLPI "Interfaces to NLP solvers"
368 * - @subpage EXPRINT "Interfaces to expression interpreters"
369 * - @subpage PARAM "additional user parameters"
370 * - @subpage TABLE "Statistics tables"
371 * - @subpage BENDER "Benders' decomposition"
372 * + @subpage BENDERSCUT "Benders' decomposition cuts"
373 */
374/**@page HOWTOUSESECTION How to use ...
375 *
376 * - @subpage CONF "Conflict analysis"
377 * - @subpage TEST "How to run automated tests with SCIP"
378 * - @subpage COUNTER "How to use SCIP to count feasible solutions"
379 * - @subpage REOPT "How to use reoptimization in SCIP"
380 * - @subpage CONCSCIP "How to use the concurrent solving mode in SCIP"
381 * - @subpage DECOMP "How to provide a problem decomposition"
382 * - @subpage BENDDECF "How to use the Benders' decomposition framework"
383 * - @subpage TRAINESTIMATION "How to train custom tree size estimation for SCIP"
384 * - @subpage PROBINGDIVING "How to use probing and diving mode"
385 */
386
387/**@page AUTHORS SCIP Authors
388 *
389 * A list of all current and former developers as well as contributors can
390 * be found on the
391 * <a class="el" href="http://scipopt.org/#developers">Main Web Page</a>.
392 *
393 */
394
395/**@page EXTERNALDOC Links to external documentation
396 *
397 * <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.
398 *
399 */
400
401/**@page CHG Release notes and changes between different versions of SCIP
402 *
403 * New features, peformance improvements, and interface changes between different versions of SCIP are documented in the
404 * release notes:
405 *
406 * - \subpage RN80 "SCIP 8.0"
407 * - \subpage RN70 "SCIP 7.0"
408 * - \subpage RN60 "SCIP 6.0"
409 * - \subpage RN50 "SCIP 5.0"
410 * - \subpage RN40 "SCIP 4.0"
411 * - \subpage RN32 "SCIP 3.2"
412 * - \subpage RN31 "SCIP 3.1"
413 * - \subpage RN30 "SCIP 3.0"
414 * - \subpage RN21 "SCIP 2.1"
415 * - \subpage RN20 "SCIP 2.0"
416 * - \subpage RN12 "SCIP 1.2"
417 * - \subpage RN11 "SCIP 1.1"
418 * - \subpage RN10 "SCIP 1.0"
419 * - \subpage RN09 "SCIP 0.9"
420 * - \subpage RN08 "SCIP 0.8"
421 * - \subpage RN07 "SCIP 0.7"
422 *
423 */
424
425/**@page WHATPROBLEMS What types of optimization problems does SCIP solve?
426 *
427 * As a stand-alone solver, \SCIP can solve mixed-integer nonlinear programs \b (MINLPs), to which it applies
428 * an LP based spatial branch-and-cut algorithm. This method is guaranteed to solve bounded MINLPs
429 * within a given numerical tolerance in a finite amount of time. In particular, \SCIP is a stand-alone
430 * solver for mixed-integer linear programs \b (MIPs).
431 *
432 * As a framework, \SCIP also provides the tools to solve constraint optimization problems defined over
433 * integer and continuous variables. Therefore, the design of \SCIP
434 * supports the easy integration of constraints of arbitrary type into the solver.
435 * More precisely, \SCIP can handle the class of constraint integer programs \b (CIPs), which are constraint optimization problems
436 * that become linear programs (LPs) after the integer variables are fixed.
437 *
438 * @section PROBLEMCLASSES Some important subclasses of CIP and MINLP
439 *
440 * The following table gives a non-exhaustive list of common types of mathematical optimization problems that can be solved
441 * through \SCIP itself or one of its extensions. Some recommendations are given on how to compile \SCIP for a
442 * certain problem class and how make best use of \SCIP. The file format column gives some common file
443 * formats for every class. Note that since some of the mentioned problem classes are more general than others (like
444 * every LP is a MIP is an MINLP), the formats for the superclass should always work just as fine, although they
445 * may be less common for the class at hand.
446 *
447 * Please see also the pages on \ref EXAMPLES "SCIP Examples" and \ref APPLICATIONS "SCIP Applications" to learn more on how
448 * to extend \SCIP for a particular MIP, MINLP, or CIP application.
449 * All examples and applications use the C or C++ APIs of \SCIP. Please have a look at \ref INTERFACES "SCIP interfaces"
450 * to see how to use \SCIP from within other programming languages.
451 *
452 * <table class="types">
453 * <caption align="top">Some problem classes that can be solved by \SCIP</caption>
454 * <tr style="border-bottom: medium solid black;">
455 * <th>Problem class</th>
456 * <th>Mathematical problem description</th>
457 * <th>Supported file formats</th>
458 * <th>Recommendations</th>
459 * </tr>
460 * <tr>
461 * <td>Mixed-integer linear program (MIP)</td>
462 * <td>\f{align*}{
463 * \text{min} \quad& c^T x \\
464 * \text{s.t.} \quad& Ax \geq b \\
465 * &l_{j} \leq x_{j} \leq u_{j} && \forall j \in \mathcal{N} \\
466 * &x_{j} \in \mathbb{Z} && \forall j \in \mathcal{I}
467 * \f}
468 * </td>
469 * <td>
470 * <ul>
471 * <li>\ref reader_cip.h "CIP"</li>
472 * <li>\ref reader_mps.h "MPS"</li>
473 * <li>\ref reader_lp.h "LP"</li>
474 * <li>\ref reader_zpl.h "ZPL"</li>
475 * </ul>
476 * </td>
477 * <td>
478 * <ul>
479 * <li>\SCIP requires an external LP solver to solve LP relaxations, which needs to be specified
480 * at compilation time. By default, it uses SoPlex (<code>LPS=spx</code>). See \ref MAKE for a
481 * list of available LP solver interfaces and how to use them inside \SCIP.</li>
482 * <li>Compile with Zimpl support (<code>ZIMPL=true</code>) to read in Zimpl models directly.</li>
483 * <li>\SCIP comes with many different parameters. Use the provided emphasis settings (see \ref SHELL "this tutorial")
484 * to change many parameters at once and boost the performance.</li>
485 * <li>Test instances are available at <code>check/instances/MIP/</code>.</li>
486 * </ul>
487 * </td>
488 * </tr>
489 * <tr>
490 * <td>Mixed-integer nonlinear program (MINLP)</td>
491 * <td>\f{align*}{
492 * \text{min} \quad& f(x) \\
493 * \text{s.t.} \quad& g_{i}(x) \leq 0 && \forall i \in \mathcal{M} \\
494 * &l_{j} \leq x_{j} \leq u_{j} && \forall j \in \mathcal{N} \\
495 * &x_{j} \in \mathbb{Z} && \forall j \in \mathcal{I}
496 * \f}
497 * </td>
498 * <td>
499 * <ul>
500 * <li>\ref reader_cip.h "CIP"</li>
501 * <li>\ref reader_gms.h "GMS"</li>
502 * <li>\ref reader_osil.h "OSiL"</li>
503 * <li>\ref reader_pip.h "PIP"</li>
504 * <li>\ref reader_zpl.h "ZPL"</li>
505 * <li>For MIQCPS:
506 * <ul>
507 * <li>\ref reader_lp.h "LP"</li>
508 * <li>\ref reader_mps.h "MPS"</li>
509 * </ul>
510 * </li>
511 * </ul>
512 * </td>
513 * <td>
514 * <ul>
515 * <li>Compile with <code>IPOPT=true</code> for better performance.</li>
516 * <li>Compile with <code>WORHP=true</code> for better performance.</li>
517 * <li>Compile with <code>FILTERSQP=true</code> for better performance.</li>
518 * <li>See <a href="FAQ\FILEEXT#minlptypes"> Which kind of MINLPs are supported by \SCIP? </a> in the FAQ.</li>
519 * <li>There is an interface for the modelling language AMPL, see \ref INTERFACES.</li>
520 * <li>Mixed-integer quadratically constrained programs (MIQCP) can also be formulated in the file formats
521 * <ul>
522 * <li>\ref reader_lp.h "LP", and</li>
523 * <li>\ref reader_mps.h "MPS".</li>
524 * </ul>
525 * </li>
526 * <li>Test instances are available at <code>check/instances/MINLP/</code>.</li>
527 * </ul>
528 * </td>
529 * </td>
530 * <tr>
531 * <td>Constraint Integer Program (CIP)</td>
532 * <td>\f{align*}{
533 * \text{min} \quad& c^T x + d^T y \\
534 * \text{s.t.} \quad& C_i(x,y) = \text{true} && \forall i \in \mathcal{M} \\
535 * & x \in \mathbb{Z}^{p}, y \in \mathbb{R}^{n - p}
536 * \f}
537 * 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.
538 * </td>
539 * <td>
540 * <ul>
541 * <li>\ref reader_cip.h "CIP"</li>
542 * <li>\ref reader_fzn.h "FlatZinc"</li>
543 * </ul>
544 * </td>
545 * <td>
546 * <ul>
547 * <li>\SCIP supports a limited number of general constraints; see \ref CONS "How to add constraint handlers"
548 * to learn how to extend the \SCIP framework to a given CIP.</li>
549 * <li>Use the emphasis setting <code>set emphasis cpsolver</code> to completely disable LP solves and
550 * use depth-first search with periodic restarts, see also
551 * <a href="FAQ\FILEEXT#scipascpsolver"> Can I use \SCIP as a pure CP solver? </a> in the FAQ.</li>
552 * <li>Test instances are available at <code>check/instances/CP</code>.</li>
553 * </ul>
554 * </td>
555 * <tr>
556 * <td>Convex MINLP</td>
557 * <td>Like MINLP, \f$f\f$ and all \f$g_i\f$ are \b convex.</td>
558 * <td>see MINLP formats</td>
559 * <td>
560 * <ul>
561 * <li>See the comments for MINLP.</li>
562 * <li>In addition, use <code>constraints/nonlinear/assumeconvex = TRUE</code> to inform \SCIP about a convex
563 * problem in cases where the automated detection is not strong enough.</li>
564 * <li>Test instances are available at <code>check/instances/MINLP/circle.lp</code>.</li>
565 * </ul>
566 * </td>
567 * </td>
568 * <tr>
569 * <td>Linear program (LP)</td>
570 * <td>\f{align*}{
571 * \text{min} \quad& c^T x \\
572 * \text{s.t.} \quad& Ax \geq b \\
573 * & x_{j} \geq 0 && \forall j \in \mathcal{N}
574 * \f}
575 * </td>
576 * <td>see MIP formats</td>
577 * <td>See <a href="FAQ\FILEEXT#scipaslpsolver">Can I use \SCIP as a pure LP solver</a> in the FAQ.</td>
578 * </td>
579 * <tr>
580 * <td>Pseudoboolean optimization</td>
581 * <td>\f{align*}{
582 * \text{min} \quad& c^T x \\
583 * \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} \\
584 * &x_{j} \in \{0,1\} && \forall j \in \mathcal{N}
585 * \f}
586 * </td>
587 * <td>
588 * <ul>
589 * <li>\ref reader_wbo.h "WBO"</li>
590 * <li>\ref reader_opb.h "OPB"</li>
591 * </ul>
592 * </td>
593 * <td>
594 * <ul>
595 * <li>Test instances are available at <code>check/instances/PseudoBoolean/</code>.</li>
596 * </ul>
597 * </td>
598 * </tr>
599 * <tr>
600 * <td>Satisfiability (SAT) and variants</td>
601 * <td>\f{align*}{
602 * \text{min} \quad& 0 \\
603 * \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}\\
604 * &x_{j} \in \{\text{false},\text{true}\} && \forall j \in \mathcal{N}
605 * \f}
606 * </td>
607 * <td>
608 * <ul>
609 * <li>\ref reader_cnf.h "CNF"</li>
610 * </ul>
611 * </td>
612 * <td>
613 * <ul>
614 * <li>Use the emphasis setting <code>set emphasis cpsolver</code> to completely disable LP solves and
615 * use depth-first search with periodic restarts, see also
616 * <a href="FAQ\FILEEXT#scipascpsolver"> Can I use \SCIP as a pure CP/SAT solver? </a> in the FAQ.</li>
617 * <li>Test instances are available at <code>check/instances/SAT/</code>.</li>
618 * </ul>
619 * </td>
620 * </tr>
621 * <tr>
622 * <td>Multicriteria optimization</td>
623 * <td>\f{align*}{
624 * \text{min} \quad &(c_1^T x,\ldots,c_k^T x) \\
625 * \text{s.t. } \quad& Ax \geq b \\
626 * &x \in \mathbb{K}^n
627 * \f}
628 * where \f$\mathbb{K}\f$ is either \f$\mathbb{Z}\f$ or \f$\mathbb{R}\f$.
629 * </td>
630 * <td colspan="3"> see the <a href="http://polyscip.zib.de/">PolySCIP web page</a></td>
631 * </tr>
632 * <tr>
633 * <td>Mixed-integer semidefinite program (MISDP)</td>
634 * <td>\f{align*}{
635 * \text{inf} \quad \thinspace & b^T y \\
636 * \text{s.t.} \quad & \sum_{j=1}^m A_j\, y_j - A_0 \succeq 0 \\
637 * & y_j \in \mathbb{Z} && \forall\, j \in \mathcal{I}
638 * \f}
639 * </td>
640 * <td colspan="3"> see the <a href="http://www.opt.tu-darmstadt.de/scipsdp/">SCIP-SDP web page</a></td>
641 * </tr>
642 * </table>
643 *
644 *
645 */
646
647/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
648
649/**@page CODE Coding style guidelines
650 *
651 * We follow the following coding style guidelines and recommend them for all developers.
652 *
653 * @section CODESPACING Spacing:
654 *
655 * - Indentation is 3 spaces. No tabs anywhere in the code.
656 * - Every opening parenthesis requires an additional indentation of 3 spaces.
657 *
658 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleParenIndent}
659 *
660 * - Spaces around all operators.
661 * - Spaces around the arguments inside an if/for/while-statement, as well as inside macros (e.g., SCIP_CALL).
662 * - No spaces between control structure keywords like "if", "for", "while", "switch" and the corresponding brackets.
663 * - No spaces between a function name and the parenthesis in both the definition and function calls.
664 * - Braces are on a new line and not indented.
665 * - Braces in if/for-statements should only be omitted if they enclose a single line.
666 *
667 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleIfFor}
668 *
669 * - In function declarations, every parameter is on a new line. The name of the parameter starts at column 26,
670 * the comment starts at column 46 (if column-count starts with 1).
671 * - Maximal line length is 120 characters.
672 * - Always only one declaration in a line.
673 * - Variable names should be all lower case.
674 *
675 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleDeclaration}
676 *
677 * - Blank lines are inserted where it improves readability.
678 * - Multiple blank lines are used to structure the code where single blank lines are insufficient,
679 * e.g., between differrent sections of the code.
680 *
681 * @refsnippet{src/scip/heur_xyz.c,SnippetCodeStyleBlanks}
682 *
683 * @section CODENAMING Naming:
684 *
685 * - Use assert() to show preconditions for the parameters, invariants, and postconditions.
686 * - Make all functions that are not used outside the module 'static'.
687 * - Naming should start with a lower case letter.
688 *
689 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleStaticAsserts}
690 *
691 * - All global functions start with "SCIP". In the usual naming scheme this is followed by the object and a method name
692 * like in SCIPlpAddRow(). Functions return TRUE or FALSE should be named like SCIPisFeasEQ().
693 *
694 * @refsnippet{src/scip/scip_numerics.h,SnippetCodeStyleNaming}
695 *
696 * - For each structure there is a typedef with the name in all upper case.
697 * - Defines should be named all upper case.
698 *
699 * @refsnippet{src/scip/type_set.h,SnippetCodeStyleExample}
700 *
701 * @section CODEDOC Documentation:
702 *
703 * - Document functions, parameters, and variables in a doxygen conformed way.
704 * - Please do not leave code in comments that has been commented out, don't use `#if
705 * 0`. Instead put the code within defines `#ifdef SCIP_DISABLED_CODE` and add an explanation.
706 * - Todos need double stars to be registered by doxygen.
707 * - When documenting methods, the first brief description starts with lower case and is separated by semi-colons, if necessary
708 * The longer description starts capitalized and consists of complete sentences.
709 * If the documentation consists of multiple lines, the comment end must be on a new line.
710 *
711 * @refsnippet{src/scip/scip_datastructures.h,SnippetCodeStyleComment}
712 *
713 *
714 * @section XEMACS Customize (x)emacs
715 *
716 * If you are using (x)emacs, you can use the following customization for the c++-mode. These settings satisfy the
717 * coding guidelines of \SCIP.
718 *
719 * \include codestyle/emacs_scip_codestyle.el
720 *
721 *
722 * @section ECLIPSE Customize eclipse
723 *
724 * Eclipse user can use the profile below. This profile does not match the \SCIP coding guideline completely.
725 *
726 * \include codestyle/eclipse_scip_codestyle.xml
727 */
728
729/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
730
731/**@page START How to start a new project
732 *
733 * Once you succeeded installing \SCIP together with an LP-solver on your system,
734 * you have a powerful tool for solving MIPs, MIQCPs,
735 * MINLPs, etc... at hand. \SCIP can also be customized to the type of problems you
736 * are working on by additional plugins.
737 * Instructions on how to write a new plugin and include it in \SCIP can be found in the corresponding
738 * \ref HOWTOADD "How to add ... pages".
739 *
740 * \SCIP can also be used for writing your own branch-and-cut or branch-and-cut-and-price code. \SCIP already
741 * provides a number of existing code examples which we suggest as both reference and starting point
742 * for these kinds of projects.
743 * Below, you find some hints of how to start such a project.
744 *
745 * @section START_CHOICE Choose an example project
746 *
747 * The example should be chosen depending on the programming language (<b>C</b> or <b>C++</b>) and the purpose
748 * (<b>branch-and-cut</b> or <b>branch-and-cut-and-price</b>) of your project.
749 * <br>
750 * We suggest the use of one of the following examples:
751 * - The \ref VRP_MAIN "Vehicle Routing Problem Example" is a <b>branch-and-cut-and-price</b> (column generation)-code
752 * in <b>C++</b>.
753 * - The \ref BINPACKING_MAIN "Binpacking Example"
754 * and the \ref COLORING_MAIN "Coloring application" are
755 * <b>branch-and-cut-and-price</b> (column generation)-codes in <b>C</b>.
756 * - The \ref TSP_MAIN "TSP example"
757 * is a <b>branch-and-cut</b>-code in <b>C++</b>.
758 * - The \ref LOP_MAIN "LOP example"
759 * is a <b>branch-and-cut</b>-code in <b>C</b>.
760 *
761 * More examples can be found in the \ref EXAMPLES "list of Examples".
762 *
763 * - Copy one of the examples in the <code>examples</code> directory (in the \SCIP root
764 * directory). For instance, type
765 * \verbatim
766 cp -r examples/Binpacking/ ../SCIPProject/ ; cd ../SCIPProject
767 \endverbatim
768 * from the \SCIP root directory for copying the content of the <code>Binpacking</code>-example into a fresh
769 * directory named SCIPProject in the parent directory of the \SCIP root directory and jumping to
770 * the new SCIPProject directory rightafter.
771 *
772 * @section START_CMAKE Building with CMake
773 *
774 * It is recommended for all new users to use the CMake build system configuration, if available on their platform.
775 *
776 * - Open the <code>CMakeLists</code> (some examples projects have a subdirectory "check" for testing) via
777 * \verbatim
778 kate CMakeLists.txt & kate check/CMakeLists.txt # if check/CMakeLists.txt is available
779 \endverbatim
780 * and replace all instances of the copied project's name (e.g. <code>binpacking</code>) with your project name.
781 * - Create a new subdirectory, jump to the new directory and use cmake specifying your \SCIP directory. For instance, type
782 * \verbatim
783 mkdir Release ; cd Release ; cmake .. -DSCIP_DIR=../scip/Release
784 \endverbatim
785 * 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.
786 *
787 *
788 * @section START_MAKE Building with the Makefile system
789 *
790 * If CMake should be unavailable on your targeted platform, try the classic Makefile system of SCIP.
791 *
792 * - Open the <code>Makefile</code> via
793 * \verbatim
794 kate Makefile
795 \endverbatim
796 * and edit the following variables at the top to have a compilable code:
797 *
798 * - specify a correct path to the \SCIP root (<code>SCIPDIR</code>)
799 * - rename the targets name (<code>MAINNAME</code>)
800 * - adjust the source file names (<code>MAINOBJ</code>).
801 * .
802 * - Once you have edited the makefile, you can use all the flags that can be used in \SCIP to
803 * compile your code, see \ref MAKE.
804 *
805 */
806
807/**@page EXAMPLES Example projects
808 *
809 * \SCIP contains several examples that demonstrate its usage. They are contained in the &quot;examples&quot; directory
810 * in the source code distribution.
811 *
812 * <table>
813 * <tr>
814 * <td colspan="2">
815 * <b>
816 * Callable library
817 * </b>
818 * </td>
819 * </tr>
820 * <tr>
821 * <td>
822 * @subpage CALLABLELIBRARY_MAIN "Callable Library Example"
823 * </td>
824 * <td>
825 * An example showing how to setup constraints (esp. nonlinear ones) when using \SCIP as callable library.
826 * </td>
827 * </tr>
828 * <tr>
829 * <td>
830 * @subpage MIPSOLVER_MAIN "MIP solver"
831 * </td>
832 * <td>
833 * A minimal implementation for using \SCIP included into another source code
834 * </td>
835 * </tr>
836 * <tr>
837 * <td>
838 * @subpage QUEENS_MAIN "The n-Queens Problem"
839 * </td>
840 * <td>
841 * Using SCIP's callable library for solving the n-queens problem.
842 * </td>
843 * </tr>
844 * <tr>
845 * <td colspan="2">
846 * <b>
847 * Extending SCIP by custom plugins
848 * </b>
849 * </td>
850 * </tr>
851 * <tr>
852 * <td>
853 * @subpage EVENTHDLR_MAIN "Event handler"
854 * </td>
855 * <td>
856 * A small example illustrating the use of an event handler.
857 * </td>
858 * </tr>
859 * <tr>
860 * <td>
861 * @subpage GMI_MAIN "Gomory mixed integer cut example"
862 * </td>
863 * <td>
864 * An example about Gomory mixed-integer cuts.
865 * </td>
866 * </tr>
867 * <tr>
868 * <td>
869 * @subpage RELAXATOR_MAIN "Relaxator example"
870 * </td>
871 * <td>
872 * An example about using custom relaxators.
873 * </td>
874 * </tr>
875 * <tr>
876 * <td colspan="2">
877 * <b>
878 * Branch-and-cut
879 * </b>
880 * </td>
881 * </tr>
882 * <tr>
883 * <td>
884 * @subpage SUDOKU_MAIN "Sudoku example"
885 * </td>
886 * <td>
887 * An example solving sudokus.
888 * </td>
889 * </tr>
890 * <tr>
891 * <td>
892 * @subpage LOP_MAIN "Linear Ordering"
893 * </td>
894 * <td>
895 * An example for implementing a constraint handler.
896 * </td>
897 * </tr>
898 * <tr>
899 * <td>
900 * @subpage TSP_MAIN "The TSP example"
901 * </td>
902 * <td>
903 * A short implementations of a constraint handler, two easy combinatorial heuristics, a file reader, etc. which
904 * demonstrate the usage of \SCIP as a branch-and-cut-framework for solving traveling salesman problem instances.
905 * </td>
906 * </tr>
907 * <tr>
908 * <td colspan="2">
909 * <b>
910 * Branch-and-price
911 * </b>
912 * </td>
913 * </tr>
914 * <tr>
915 * <td>
916 * @subpage BINPACKING_MAIN "Binpacking"
917 * </td>
918 * <td>
919 * An implementation of the column generation approach for the binpacking problem. It includes a customized reader,
920 * Ryan/Foster branching rule, (global) problem data, variable data, and constraint handler.
921 * </td>
922 * </tr>
923 * <tr>
924 * <td>
925 * @subpage VRP_MAIN "Vehicle Routing"
926 * </td>
927 * <td>
928 * A solver for a simple capacity-constrained vehicle routing problem, which is based on pricing tours via a dynamic
929 * programming algorithm.
930 * </td>
931 * </tr>
932 * <tr>
933 * <td colspan="2">
934 * <b>
935 * Benders' decomposition
936 * </b>
937 * </td>
938 * </tr>
939 * <tr>
940 * <td>
941 * @subpage SCFLP_MAIN "Stochastic capacitated facility location problem"
942 * </td>
943 * <td>
944 * A stochastic programming problem that demonstrates the use of the Benders' decomposition framework within SCIP.
945 * </td>
946 * </tr>
947 * </table>
948 */
949
950/** @page APPLICATIONS Application projects
951 *
952 * There are several extensions of \SCIP for particular applications included in the release. They are contained in the &quot;applications&quot; directory
953 * in the source code distribution.
954 *
955 * <table>
956 * <tr>
957 * <td>
958 * @subpage COLORING_MAIN
959 * </td>
960 * <td>
961 * An implementation of the column generation approach for graph coloring of Mehrotra and Trick.
962 * </td>
963 * </tr>
964 * <tr>
965 * <td>
966 * @subpage CYCLECLUSTERING_MAIN
967 * </td>
968 * <td>
969 * Branch-and-cut implementation of a graph partitioning problem used for Markov state models.
970 * </td>
971 * </tr>
972 * <tr>
973 * <td>
974 * @subpage MINIISC_MAIN
975 * </td>
976 * <td>
977 * A solver that computes irreducible infeasible subsystems using Benders decomposition
978 * </td>
979 * </tr>
980 * <tr>
981 * <td>
982 * @subpage POLYSCIP_MAIN
983 * </td>
984 * <td>
985 * A solver for multi-objective optimization problems.
986 * </td>
987 * </tr>
988 * <tr>
989 * <td>
990 * @subpage RINGPACKING_MAIN "Ringpacking"
991 * </td>
992 * <td>
993 * An implementation of the column generation approach for the Ringpacking Problem. It includes a customized reader,
994 * (global) problem data, variable data, and constraint handler.
995 * </td>
996 * </tr>
997 * <tr>
998 * <td>
999 * @subpage SCHEDULER_MAIN
1000 * </td>
1001 * <td>
1002 * A solver for scheduling problems.
1003 * </td>
1004 * </tr>
1005 * </table>
1006 *
1007 */
1008
1009
1010/**@page SHELL Tutorial: the interactive shell
1011 *
1012 * If you are using \SCIP as a black box solver, here you will find some tips and tricks what you can do.
1013 *
1014 * @section TUTORIAL_OPTIMIZE Read and optimize a problem instance
1015 *
1016 * @subsection SHELL_PREREQUISITES "Prerequisites"
1017 *
1018 * First of all, we need a \SCIP binary and an example problem file to work with.
1019 * For installation we refer you to the \ref INSTALL section.
1020 *
1021 * Therefore, you can either download the \SCIP standard distribution (which includes problem files) and compile it on your own or you can download a
1022 * precompiled binary and an example problem separately. \SCIP can read files in LP, MPS, ZPL, WBO, FZN, PIP, OSiL, and
1023 * other formats (see \ref FILEREADERS).
1024 *
1025 * If you want to download the source code of the \SCIP standard distribution, we recommend to go to the <a
1026 * href="https://scipopt.org/#download">SCIP download section</a>, download the latest release,
1027 * inflate the tarball (e.g., with "tar xzf scipoptsuite-[version].tgz"), and follow the instructions
1028 * in the INSTALL file. The instance stein27, which will serve as an example in this tutorial, can be found under
1029 * scipoptsuite-[version]/scip-[version]/check/instances/MIP/stein27.fzn.
1030 * Alternatively you can download an instance file from the <a href="https://miplib.zib.de/tag_benchmark.html">MIPLIB 2017 page</a>.
1031 *
1032 * If you want to download a precompiled binary, go to the <a href="http://scipopt.org/#download">SCIP download
1033 * section</a> and download an appropriate binary for your operating system. The \SCIP source code distribution already comes with
1034 * the example instance used throughout this tutorial. To follow this tutorial with a precompiled binary, we recommend downloading the instance
1035 * <a href="http://miplib2010.zib.de/miplib3/miplib3/stein27.mps.gz">stein27</a> from
1036 * the <a href="http://miplib2010.zib.de/miplib3/miplib.html">MIPLIB 3.0</a> homepage.
1037 *
1038 * @subsection SHELL_AFTERINSTALL "After installation"
1039 *
1040 * Now start your binary, without any arguments. This opens the interactive shell, which should look somehow like this:
1041 *
1042 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetVersion
1043 *
1044 * First of all "help" shows you a list of all available shell commands. Brackets indicate a submenu with further options.
1045 *
1046 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetHelp
1047 *
1048 * 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
1049 * solution" to show the nonzero variables of the best found solution.
1050 *
1051 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetOpt1
1052 *
1053 * What do we see here? After "optimize", SCIP first goes into presolving. Not much is happening for this instance, just
1054 * the linear constraints get upgraded to more specific types. Each round of presolving will be displayed in a single
1055 * line, with a short summary at the end. Then, we see the actual solving process. The table output of the branch-and-cut
1056 * solving process is very detailed during the root node. Afterwards, a new line is displayed every 100th node.
1057 * Furthermore, every new incumbent solution triggers a new table row, starting with a character to indicate the
1058 * heuristic that found the solution. Which letter represents which heuristic can be seen with the
1059 * "display heuristics" command, see \ref TUTORIAL_STATISTICS for an example.
1060 *
1061 * After some lines the root node processing is finished. From now on, we will see an output line every hundredth node or
1062 * whenever a new incumbent is found. After some more nodes, the "dualbound" starts
1063 * moving, too. At one point, both will be the same, and the solving process terminates, showing us some wrap-up
1064 * information.
1065 *
1066 * The exact performance may of course vary among different architectures and operating systems. Do not be worried if
1067 * your installation needs more or less time or nodes to solve. Also, this instance has more than 2000 different optimal
1068 * solutions. The optimal objective value always has to be 18, but the solution vector may differ. If you are interested
1069 * in this behavior, which is called "performance variability", you may have a look at the MIPLIB2010 paper.
1070 *
1071 * @section TUTORIAL_FILEIO Writing problems and solutions to a file
1072
1073 * \SCIP can also write information to files. E.g., we could store the incumbent solution to a file, or output the
1074 * problem instance in another file format (the LP format is much more human readable than the MPS format, for example).
1075 *
1076 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetWriteSolutions
1077 *
1078 * Passing starting solutions can increase the solving performance so that \SCIP does not need to construct an initial feasible solution
1079 * by itself. After reading the problem instance, use the "read" command again, this time with a file containing solution information.
1080 * Solutions can be specified in a raw or xml-format and must have the file extension ".sol", see the documentation of the
1081 * \ref reader_sol.h "solution reader of SCIP" for further information.
1082 *
1083 * Customized settings are not written or read with the "write" and "read" commands, but with the three commands
1084 *
1085 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSaveSettingsOverview
1086 *
1087 * See the section on parameters \ref TUTORIAL_PARAMETERS for more information.
1088 *
1089 * @section TUTORIAL_STATISTICS Displaying detailed solving statistics
1090 *
1091 * We might want to have some more information now. Which of the heuristics found solutions? Which plugins
1092 * were called during the solutions process and how much time did they spend?
1093 * Information on certain plugin types (e.g., heuristics, branching rules, separators) is displayed via
1094 * "display <plugin-type>", information on the solution process via "display statistics", and "display problem"
1095 * shows the current instance.
1096 *
1097 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetDisplayStatistics
1098 *
1099 * The statistics obtained via "display statistics" are quite comprehensive,
1100 * thus, we just explain a few lines here. Information is grouped by the plugin type. For the primal heuristics,
1101 * the execution time in seconds is shown as well as the number of calls to the heuristic, and its success regarding
1102 * the number of (best) solutions found by that heuristic. Appropriate statistics are also shown for presolvers, constraint handlers,
1103 * separators, propagators, the search tree, etc. User-written plugins will appear automatically in these statistics,
1104 * after they were included into \SCIP.
1105 *
1106 * @section TUTORIAL_PARAMETERS Changing parameters from the interactive shell
1107 *
1108 * Now, we can start playing around with parameters. The primal heuristics Rounding and shifting seem to be quite successful on this instance,
1109 * wondering what happens if we disable them? Or what happens, if we are even more rigorous and disable all heuristics?
1110 * Or if we do the opposite and use aggressive heuristics?
1111 *
1112 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSetSettings
1113 *
1114 * We can navigate through the menus step-by-step and get a list of available options and submenus. Therefore, we select
1115 * "set" to change settings, "heuristics" to change settings of primal heuristics, and "shifting" for that particular
1116 * heuristic. Then we see a list of parameters (and yet another submenu for advanced parameters), and disable this
1117 * heuristic by setting its calling frequency to -1. If we already know the path to a certain setting, we can directly
1118 * type it (as for the rounding heuristic in the above example). Note that we do not have to use the full names, but we
1119 * may use short versions, as long as they are unique.
1120 *
1121 * To solve a problem a second time, we have to read it in again before starting the optimization process.
1122 *
1123 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetOpt2
1124 *
1125 * Okay, what happened here? First, we reset all parameters to their default values, using "set default". Next, we
1126 * loaded some meta-parameter settings (also see <a href="FAQ.php#howtochangebehaviour">the FAQ</a>), to apply primal heuristics
1127 * more aggressively. \SCIP shows us, which single parameters it changed therefore. Additionally, for pedagogical purposes,
1128 * we set the node limit to 200. Now, the optimal solution is already found at the root node, by a heuristic which is
1129 * deactivated by default. Then, after node 200, the user defined node limit is reached which interrupts the solving
1130 * process, We see that now in the short status report, primal and dual bound are different, thus, the problem is not solved
1131 * yet. Nevertheless, we could access statistics, see the current incumbent solution, change parameters and so on.
1132 * Entering "optimize" we continue the solving process from the point on at which it has been interrupted.
1133 *
1134 * Once you found a non-default parameter setting that you wish to save and use in the future, use either the command
1135 *
1136 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSaveSettingsFull
1137 *
1138 * to save <b>all</b> parameter values to the specified file, or
1139 *
1140 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSaveSettingsDiff
1141 *
1142 * in order to save only the nondefault parameters. The latter has several advantages, you can, e.g., combine parameter
1143 * settings from multiple settings files stored by the latter command, as long as they only affect mutually exclusive
1144 * parameter values.
1145 *
1146 * For loading a previously stored settings file, use the "load" command:
1147 *
1148 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetLoadSettings
1149 *
1150 * Special attention should be drawn to the reserved settings file name "scip.set"; whenever the \SCIP interactive shell
1151 * is started from a working directory that contains a settings file with the name "scip.set", it will be automatically
1152 * replace the default settings.
1153 *
1154 * For using special settings for automated tests as described in \ref TEST, save your custom settings in a subdirectory
1155 * "SCIP_HOME/settings".
1156 *
1157 *
1158 * We hope this tutorial gave you an overview of what is possible using the \SCIP interactive shell. Please also read our
1159 * \ref FAQ, in particular the section "Using SCIP as a standalone MIP/MINLP-Solver".
1160 *
1161 */
1162
1163/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
1164
1165/**@page DOC How to search the documentation for interface methods
1166 *
1167 * 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.
1168 * - It contains interface methods for all SCIP structs, both in the solver core or in one of the plugins.
1169 * - Plugins are mostly independent from each other, so to use them it is usually enough to browse the \ref PUBLICCOREAPI "Core API".
1170 * - If you want to add your own plugins, see the \ref HOWTOADD pages for exhaustive information for each plugin type.
1171 * - If you are learning SCIP with a concrete project in mind, looking at the available \ref EXAMPLES page may help you
1172 * getting started.
1173 * - See also \ref START "How to start a new project"
1174 *
1175 * 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_",
1176 * such as \ref type_var.h , which contains enums and type definitions related to \ref PublicVariableMethods "SCIP problem variables".
1177 * Definitions of the actual structs can be found in separate header files starting with "struct_".
1178 * All method definitions of the public SCIP API are split across header files starting with "pub_" such as \ref pub_cons.h
1179 * or headers starting with "scip_" such as \ref scip_cons.h .
1180 * The latter headers starting with "scip_" contain more complex methods, which always receive a scip pointer as first argument.
1181 * Those methods may affect several individual components controlled by SCIP. Such a method is SCIPbranchVar(), which
1182 * affects the search tree, which is controlled by SCIP itself and not meant to be accessed by user plugins.
1183 *
1184 * It should be sufficient to include scip/scip.h and scip/scipdefplugins.h for having all
1185 * needed functionality available in a project.
1186 *
1187 * If, for example, you are looking for information on how to create a problem instance, here are some steps you can take:
1188 *
1189 * 1. Browse the SCIP Core API and follow the path \ref PUBLICAPI > \ref PUBLICCOREAPI > \ref PublicProblemMethods > \ref GlobalProblemMethods > SCIPcreateProb()
1190 * 2. Here you can find information on the function's return value, preconditions, postconditions, parameters, as well as related functions.
1191 * 3. If you are unsure of how to use some of the parameters, it is worth looking for a basic version of the function.
1192 * 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
1193 * 'References' and 'Referenced by' section of the function documentation. In this case, you can find `SCIPcreateProbBasic()`.
1194 *
1195 * The opposite case is that you already know the name of a function as, e.g., SCIPbranchVar().
1196 *
1197 * 1. Type the name of the function into the search bar to find the function documentation.
1198 * 2. In addition, you can find related methods by browsing the neighboring functions of the same group.
1199 * 3. In this example, you may now learn about SCIPgetNLPBranchCands() to query all integer
1200 * variables with fractional LP solution value, which are good candidates for classical branching on variables.
1201 *
1202 * Note that the \ref INTERNALAPI "private SCIP API" contains more complex functions and data structures that fill specialized roles and
1203 * is only for developers.
1204 * Those functions are **not** exported to the library and are therefore **not available in user projects** using the \ref PUBLICAPI "public SCIP API".
1205 */
1206
1207/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
1208
1209/**@page CONS How to add constraint handlers
1210 *
1211 * A constraint handler defines the semantics and the algorithms to process constraints of a certain class. A single
1212 * constraint handler is responsible for all constraints belonging to its constraint class. For example, there is
1213 * one \ref cons_knapsack.h "knapsack constraint handler" that ensures solutions are only accepted if they satisfy all
1214 * knapsack constraints in the model. \n A complete list of all constraint handlers contained in this release can be
1215 * found \ref CONSHDLRS "here".
1216 *
1217 * We now explain how users can add their own constraint handlers.
1218 * For an example, look into the subtour constraint handler (examples/TSP/src/ConshdlrSubtour.cpp) of the
1219 * \ref TSP_MAIN project.
1220 * The example is written in C++ and uses the C++ wrapper classes.
1221 * However, we will explain the implementation of a constraint handler using the C interface.
1222 * It is very easy to transfer the C explanation to C++; whenever a method should be implemented using the
1223 * SCIP_DECL_CONS... notion, reimplement the corresponding virtual member function of the abstract scip::ObjConshdlr
1224 * base class.
1225 *
1226 * Additional documentation for the callback methods of a constraint handler can be found in the file
1227 * type_cons.h.
1228 *
1229 * Here is what you have to do (assuming your constraint handler should be named "subtour"):
1230 * -# Copy the template files src/scip/cons_xyz.c and src/scip/cons_xyz.h into files "cons_subtour.c"
1231 * and "cons_subtour.h".
1232 * \n
1233 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
1234 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
1235 * -# Use `SCIPincludeConshdlrSubtour()` in order to include the constraint handler into your SCIP instance,
1236 * e.g., in the main file of your project (see, e.g., src/cppmain.cpp in the TSP example). \n
1237 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
1238 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "subtour".
1239 * -# Adjust the \ref CONS_PROPERTIES "properties of the constraint handler".
1240 * -# Define the \ref CONS_DATA "constraint data and the constraint handler data". This is optional.
1241 * -# Implement the \ref CONS_INTERFACE "interface methods".
1242 * -# Implement the \ref CONS_FUNDAMENTALCALLBACKS "fundamental callback methods".
1243 * -# Implement the \ref CONS_ADDITIONALCALLBACKS "additional callback methods". This is optional.
1244 *
1245 *
1246 * @section CONS_PROPERTIES Properties of a Constraint Handler
1247 *
1248 * At the top of the new file "cons_subtour.c" you can find the constraint handler properties.
1249 * These are given as compiler defines. Some of them are optional, as, e.g., separation-related properties,
1250 * which only have to be defined if the constraint handler supports the related callbacks.
1251 * In the C++ wrapper class, you have to provide the constraint handler properties by calling the constructor
1252 * of the abstract base class scip::ObjConshdlr from within your constructor (see the TSP example).
1253 * The properties you have to set have the following meaning:
1254 *
1255 * @subsection CONS_FUNDAMENTALPROPERTIES Fundamental Constraint Handler properties
1256 *
1257 * \par CONSHDLR_NAME: the name of the constraint handler.
1258 * This name is used in the interactive shell to address the constraint handler.
1259 * Additionally, if you are searching for a constraint handler with SCIPfindConshdlr(), this name is looked up.
1260 * Names have to be unique: no two constraint handlers may have the same name.
1261 *
1262 * \par CONSHDLR_DESC: the description of the constraint handler.
1263 * This string is printed as a description of the constraint handler in the interactive shell of SCIP.
1264 *
1265 * \par CONSHDLR_ENFOPRIORITY: the priority of the constraint handler for constraint enforcing.
1266 * Like the separation priority, the enforcement priorities define the order in which the different constraint handlers
1267 * are called in the constraint enforcement step of the subproblem processing.
1268 * The constraint enforcement is called after the price-and-cut loop is executed (in the case that the LP is solved
1269 * at the current subproblem).
1270 * \n
1271 * The integrality constraint handler has an enforcement priority of 0.
1272 * That means, if a constraint handler has negative enforcement priority, it only has to deal with integral solutions
1273 * in its enforcement methods, because for fractional solutions, the integrality constraint handler would have
1274 * created a branching, thereby aborting the enforcement step.
1275 * If you want to implement a constraint-depending branching rule (for example, SOS branching on special ordered
1276 * set constraints), you have to assign a positive enforcement priority to your constraint handler.
1277 * In this case, you have to be able to deal with fractional solutions.
1278 * \n
1279 * See \ref CONSENFOLP and \ref CONSENFOPS for further details of the separation callback.
1280 *
1281 * \par CONSHDLR_CHECKPRIORITY: the priority of the constraint handler for checking feasibility.
1282 * Like the separation priority, the checking priorities define the order in which the different constraint handlers
1283 * are called to check the feasibility of a given primal solution candidate.
1284 * The integrality constraint handler has a checking priority of 0.
1285 * That means, constraint handlers with negative checking priorities only have to deal with integral solutions.
1286 *
1287 * \par CONSHDLR_EAGERFREQ: the default frequency for using all instead of only the useful constraints in separation, propagation and enforcement.
1288 * If \em constraint \em aging is activated, some constraints that were not useful in the past for propagation or
1289 * separation are marked to be \em obsolete.
1290 * Usually, the obsolete constraints are not presented to the separation and propagation methods of the constraint
1291 * handlers, such that the constraint handlers only process the non-obsolete constraints.
1292 * However, every n'th call, with n being the EAGERFREQ of the constraint handler, all constraints are presented to the
1293 * separation and propagation methods of the constraint handler.
1294 * This gives obsolete constraints the chance of becoming non-obsolete again.
1295 * \n
1296 * If the eager evaluation frequency is set to -1, obsolete constraints are never presented to the separation and
1297 * propagation methods.
1298 * A frequency of 0 means, that obsolete constraints are only used in the first call of each method.
1299 *
1300 * \par CONSHDLR_NEEDSCONS: indicates whether the constraint handler should be skipped, if no constraints are available.
1301 * Usually, a constraint handler is only executed if there are constraints of its corresponding class in the model.
1302 * For those constraint handlers, the NEEDSCONS flag should be set to TRUE.
1303 * However, some constraint handlers must be called without having a constraint of the class in the model, because
1304 * the constraint is only implicitly available.
1305 * For example, the integrality constraint handler has the NEEDSCONS flag set to FALSE, because there is no explicit
1306 * integrality constraint in the model.
1307 * The integrality conditions are attached to the variables, and the integrality constraint handler has to check
1308 * all variables that are marked to be integer for integral values.
1309 *
1310 * @subsection CONS_ADDITIONALPROPERTIES Optional Constraint Handler properties
1311 *
1312 * The following properties are optional and only need to be defined if the constraint handlers support
1313 * separation, presolving, propagation, and/or upgrade functionality.
1314 *
1315 * \par LINCONSUPGD_PRIORITY: priority of the constraint handler for upgrading of linear constraints
1316 * This property is only needed if a certain linear constraint can be upgraded to a more specific one. In one of
1317 * the first presolving rounds SCIP tries to upgrade linear constraints to more specialized constraints, such as
1318 * knapsack constraints. The upgrading calls are processed in the order of decreasing priority.
1319 *
1320 * \par NONLINCONSUPGD_PRIORITY: priority of the constraint handler for upgrading of nonlinear constraints
1321 * This property has the same effect as the LINCONSUPGD_PRIORITY parameter, see above, and should be set whenever
1322 * an upgrade functionality from a general nonlinear constraint to the more specific one is defined.
1323 *
1324 * \par CONSHDLR_SEPAFREQ: the default frequency for separating cuts.
1325 * The separation frequency defines the depth levels at which the constraint handler's separation methods \ref CONSSEPALP
1326 * and \ref CONSSEPASOL are called.
1327 * For example, a separation frequency of 7 means, that the separation callback is executed for subproblems that are
1328 * in depth 0, 7, 14, ... of the branching tree.
1329 * A separation frequency of 0 means, that the separation method is only called at the root node.
1330 * A separation frequency of -1 disables the separation method of the constraint handler.
1331 * \n
1332 * The separation frequency can be adjusted by the user.
1333 * This property of the constraint handler only defines the default value of the frequency.
1334 * If you want to have a more flexible control of when to execute the separation algorithm, you have to assign
1335 * a separation frequency of 1 and implement a check at the beginning of your separation algorithm whether you really
1336 * want to execute the separator or not.
1337 * If you do not want to execute the method, set the result code to SCIP_DIDNOTRUN.
1338 *
1339 * \par CONSHDLR_SEPAPRIORITY: the priority of the constraint handler for separation. (optional: to be set only if the constraint handler supports separation)
1340 * In each separation round during the price-and-cut loop of the subproblem processing or during the separation loop
1341 * of the primal solution separation, the separators and separation methods of the constraint handlers are called in
1342 * a predefined order, which is given by the priorities of the separators and the separation priorities of the
1343 * constraint handlers.
1344 * First, the separators with non-negative priority are called in the order of decreasing priority.
1345 * Next, the separation methods of the different constraint handlers are called in the order of decreasing separation
1346 * priority.
1347 * Finally, the separators with negative priority are called in the order of decreasing priority.
1348 * \n
1349 * The separation priority of the constraint handler should be set according to the complexity of the cut separation
1350 * algorithm and the impact of the resulting cuts:
1351 * Constraint handlers that provide fast algorithms that usually have a high impact (i.e., cut off a large portion of
1352 * the LP relaxation) should have a high priority.
1353 * See \ref CONSSEPALP and \ref CONSSEPASOL for further details of the separation callbacks.
1354 *
1355 * \par CONSHDLR_DELAYSEPA: the default for whether the separation method should be delayed, if other separators found cuts.
1356 * If the constraint handler's separation method is marked to be delayed, it is only executed after no other separator
1357 * or constraint handler found a cut during the price-and-cut loop.
1358 * If the separation method of the constraint handler is very expensive, you may want to mark it to be delayed until all
1359 * cheap separation methods have been executed.
1360 *
1361 * \par CONSHDLR_PROPFREQ: the default frequency for propagating domains.
1362 * This default frequency has the same meaning as the CONSHDLR_SEPAFREQ with respect to the domain propagation
1363 * callback of the constraint handler.
1364 * A propagation frequency of 0 means that propagation is only applied in preprocessing and at the root node.
1365 * A propagation frequency of -1 disables the propagation method of the constraint handler.
1366 *
1367 * \par CONSHDLR_DELAYPROP: the default for whether the propagation method should be delayed, if other propagators found reductions.
1368 * This property is analogous to the DELAYSEPA flag, but deals with the propagation method of the constraint handler.
1369 *
1370 * \par CONSHDLR_PROP_TIMING: the propagation timing mask of the constraint handler.
1371 * SCIP calls the domain propagation routines at different places in the node processing loop.
1372 * This property indicates at which places the propagation routine of the constraint handler is called.
1373 * Possible values are defined in type_timing.h and can be concatenated, e.g., as in SCIP_PROPTIMING_ALWAYS.
1374 *
1375 * \par CONSHDLR_PRESOLTIMING: the timing of the constraint handler's presolving method (FAST, MEDIUM, or EXHAUSTIVE).
1376 * Every presolving round starts with the FAST presolving methods. MEDIUM presolvers are only called, if FAST presolvers did not find
1377 * enough reductions in this round so far, and EXHAUSTIVE presolving steps are only performed if all presolvers called before
1378 * in this round were unsuccessful.
1379 * Presolving methods should be assigned a timing based on how expensive they are, e.g., presolvers that provide fast algorithms that
1380 * usually have a high impact (i.e., remove lots of variables or tighten bounds of many variables) should have a timing FAST.
1381 * If a presolving method implements different algorithms of different complexity, it may also get multiple timings and check the timing
1382 * internally in the \ref CONSPRESOL callback to decide which algorithms to run.
1383 *
1384 * \par CONSHDLR_MAXPREROUNDS: the default maximal number of presolving rounds the constraint handler participates in.
1385 * The preprocessing is executed in rounds.
1386 * If enough changes have been applied to the model, an additional preprocessing round is performed.
1387 * The MAXPREROUNDS parameter of a constraint handler denotes the maximal number of preprocessing rounds the constraint
1388 * handler participates in.
1389 * A value of -1 means that there is no limit on the number of rounds.
1390 * A value of 0 means the preprocessing callback of the constraint handler is disabled.
1391 *
1392 *
1393 *
1394 * @section CONS_DATA Constraint Data and Constraint Handler Data
1395 *
1396 * Below the header "Data structures" you can find two structs called "struct SCIP_ConsData" and
1397 * "struct SCIP_ConshdlrData".
1398 * If you are using C++, you only need to define the "struct SCIP_ConsData".
1399 * The constraint handler data must be implemented as member variables of your constraint handler class.
1400 * \n
1401 * The constraint data are the information that is needed to define a single constraint of the constraint handler's
1402 * constraint class.
1403 * For example, the data of a knapsack constraint would consist of a list of variables, a list of weights, and
1404 * the capacity of the knapsack.
1405 * The data of a subtour constraint consists of the graph on which the problem is defined.
1406 * In the graph, each edge should be linked to the corresponding binary problem variable.
1407 * \n
1408 * The constraint handler data are additional variables, that belong to the constraint handler itself and which are
1409 * not specific to a single constraint.
1410 * For example, you can use these data to store parameters of the constraint handler or statistical information.
1411 * The constraint handler data are optional.
1412 * You can leave the struct empty.
1413 *
1414 *
1415 * @section CONS_INTERFACE Interface Methods
1416 *
1417 * At the bottom of "cons_subtour.c" you can find three interface methods, that also appear in "cons_subtour.h".
1418 * These are SCIPincludeConshdlrSubtour(), SCIPcreateConsSubtour(), and SCIPcreateConsSubtourBasic().
1419 * \n
1420 * The method SCIPincludeConshdlrSubtour() only has to be adjusted slightly.
1421 * It is responsible for notifying SCIP of the presence of the constraint handler by calling the method
1422 * SCIPincludeConshdlr().
1423 * It is called by the user, if (s)he wants to include the constraint handler, i.e., if (s)he wants to make
1424 * the constraint handler available to the model, and looks like this:
1425 * \dontinclude src/scip/cons_knapsack.c
1426 * -# If you are using constraint handler data, you have to <b>allocate the memory for the data</b> at this point.
1427 * You also have to initialize the fields in struct SCIP_ConshdlrData afterwards.
1428 *
1429 * \skip SCIP_RETCODE SCIPincludeConshdlrKnapsack(
1430 * \until SCIPallocBlockMemory
1431 *
1432 * -# Now, <b>SCIP gets notified</b> of the presence of the constraint handler together with its \ref CONS_FUNDAMENTALCALLBACKS "basic callbacks".
1433 *
1434 * \skip SCIPincludeConshdlrBasic
1435 * \until assert
1436 *
1437 * -# All \ref CONS_ADDITIONALCALLBACKS "additional callbacks" are added via their setter functions.
1438 *
1439 * \skip SCIPsetConshdlrCopy
1440 * \until SCIPsetConshdlrExit
1441 *
1442 * -# If the constraint handler is a specialization of a general linear or nonlinear constraint, we want to include an
1443 * <b>automatic upgrading mechanism</b> by calling the interface method
1444 *
1445 * \skip SCIPfindConshdlr
1446 * \until SCIPincludeLinconsUpgrade
1447 * or
1448 * \code
1449 * SCIP_CALL( SCIPincludeNonlinconsUpgrade(scip, nonlinconsUpgdSubtour, NULL, NONLINCONSUPGD_PRIORITY, TRUE, CONSHDLR_NAME) );
1450 * \endcode
1451 *
1452 * in the nonlinear case. See also cons_nonlinear.h for further information about the general upgrade procedure in the nonlinear case.
1453 * -# You may also add <b>user parameters</b> for your constraint handler.
1454 * Some parameters which are important to play with are added to every constraint automatically, as, e.g.,
1455 * propagation or separation frequency.
1456 * \skip SCIPaddIntParam
1457 * \until DEFAULT_SEPACARDFREQ
1458 * \skip SCIP_OKAY
1459 * \until }
1460 *
1461 *
1462 * The methods SCIPcreateConsSubtour() and SCIPcreateConsSubtourBasic() are called to create a single constraint of the constraint
1463 * handler's constraint class.
1464 * It should allocate and fill the constraint data, and call SCIPcreateCons().
1465 * Take a look at the following example from the \ref cons_knapsack.h "knapsack constraint handler":
1466 *
1467 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsCreationKnapsack}
1468 *
1469 * In this example, consdataCreate() is a local method that allocates memory for the given consdata
1470 * and fills the data with the given <code>vars</code> array. For allocating memory for the constraint data, you
1471 * can use SCIP memory allocation:
1472 * \code
1473 * SCIP_CALL( SCIPallocBlockMemory(scip, consdata) );
1474 * \endcode
1475 *
1476 *
1477 * @section CONS_CALLBACKS Callback methods of Constraint handlers
1478 *
1479 * Besides the various functions which you will implement inside your constraint handler there exists a number
1480 * of <b> callback methods </b> associated with your constraint handler. Callback methods can be regarded as
1481 * tasks which your constraint handler is able to provide to the solver. They are grouped into two
1482 * categories:
1483 *
1484 * \ref CONS_FUNDAMENTALCALLBACKS "Fundamental Callback methods" are mandatory to implement
1485 * such that your code will work. For example, every constraint handler has to provide the
1486 * functionality to state whether all of its constraints are
1487 * fulfilled by a given variable assignment. Hence, the \ref CONSCHECK "CONSCHECK" callback is
1488 * one of the fundamental (or \a basic) callbacks of a constraint handler.
1489 *
1490 * Callbacks which are not necessarily implemented are grouped together as
1491 * \ref CONS_ADDITIONALCALLBACKS "additional callbacks". Such callbacks can be used to allocate and free memory
1492 * at different stages of the solving process. Although not mandatory, it might be useful to implement
1493 * some of these callbacks, e.g., to extend your constraint handler by a
1494 * \ref CONSSEPALP "separation" or \ref CONSPRESOL "presolving" functionality.
1495 *
1496 * All callbacks should be passed to SCIP during the SCIPinclude<PLUGINTYPE><PLUGINNAME> method
1497 * (e.g., SCIPincludeConshdlrKnapsack() for the \ref cons_knapsack.h "knapsack constraint handler").
1498 * Since SCIP version 3.0, two ways of setting callbacks can be used, either via SCIPincludeConshdlr()
1499 * (all at once, as it always was), or via SCIPincludeConshdlrBasic() and setter functions for additional callbacks.
1500 * Since the basic inclusion methods are very unlikely to change and will thus
1501 * make your code more stable towards future versions of SCIP with more callbacks,
1502 * we recommend the latter choice, as explained in the \ref CONS_INTERFACE "interface" section.
1503 *
1504 * @section CONS_FUNDAMENTALCALLBACKS Fundamental Callback Methods
1505 *
1506 * By implementing the fundamental callbacks, you define the semantics of the constraint class the constraint handler
1507 * deals with.
1508 * If these methods are implemented, the resulting code is already correct and finds the optimal solution to the
1509 * given problem instance.
1510 * However, it might be very slow because the additional features, like cut separation and domain propagation, are
1511 * missing.
1512 * In the C++ wrapper class scip::ObjConshdlr, the fundamental callback methods are virtual abstract member functions.
1513 * You have to implement them in order to be able to construct an object of your constraint handler class.
1514 *
1515 * There are three fundamental callback methods that are all dealing with the feasibility of a given solution.
1516 * They are called at different places in the algorithm and have slightly different meaning.
1517 * However, it is usually reasonable to implement a single local method that is called by all of the three callback
1518 * methods with slightly modified parameters.
1519 * The fourth method provides dual information that is used for example in preprocessing.
1520 *
1521 * Additional documentation for the callback methods can be found in type_cons.h.
1522 *
1523 * @subsection CONSCHECK
1524 *
1525 * The CONSCHECK callback gets a primal solution candidate in a SCIP_SOL* data structure
1526 * and has to check this solution for global feasibility.
1527 * It has to return a result SCIP_FEASIBLE, if the solution satisfies all the constraints of the constraint handler,
1528 * and a result SCIP_INFEASIBLE if there is at least one constraint that is violated.
1529 *
1530 * If the solution is not NULL, SCIP should also be informed about the constraint violation with a call to
1531 * SCIPupdateSolConsViolation() and additionally SCIPupdateSolLPRowViolation() for every row of the constraint's current
1532 * representation in the LP relaxation, if any such rows exist.
1533 * As a convenience method, SCIPupdateSolLPConsViolation() can be used if the constraint
1534 * is represented completely by a set of LP rows, meaning that the current constraint violation is equal to the maximum
1535 * of the contraint violations of the corresponding LP rows.
1536 *
1537 * The callback is used by primal heuristics to check a constructed solution for feasibility.
1538 * That means, the constraint handler has to deal with arbitrary solutions that do not necessarily satisfy the bounds
1539 * and constraints of the local subproblem.
1540 *
1541 * The value of a variable \em var in the given solution \em sol can be accessed by calling
1542 * \code
1543 * SCIPgetSolVal(scip, sol, var)
1544 * \endcode
1545 *
1546 * For example, the \ref cons_knapsack.h "knapsack constraint handler" loops over its constraints and
1547 * calculates the scalar product \f$w^T x\f$ of weights \f$w\f$ with the solution vector \f$x\f$.
1548 * This scalar product is compared with the capacity of the knapsack constraint.
1549 * If it exceeds the capacity, the CONSCHECK method is immediately aborted with the result SCIP_INFEASIBLE.
1550 * If all knapsack constraints are satisfied, a result SCIP_FEASIBLE is returned.
1551 *
1552 * @subsection CONSENFOLP
1553 *
1554 * The CONSENFOLP method is called after the price-and-cut loop was finished and an LP solution is available.
1555 * Like the CHECK call, the ENFOLP method should return a result SCIP_FEASIBLE, if the solution satisfies all the
1556 * constraints.
1557 * However, the behavior should be different, if the solution violates some of the associated constraints.
1558 * The constraint handler may return a result SCIP_INFEASIBLE in this situation, but this is not the best what
1559 * one can do.
1560 * The ENFOLP method has the possibility of \em resolving the infeasibility by
1561 * - stating that the current subproblem is infeasible (result SCIP_CUTOFF),
1562 * - adding an additional constraint that resolves the infeasibility (result SCIP_CONSADDED),
1563 * - reducing the domain of a variable (result SCIP_REDUCEDDOM),
1564 * - adding a cutting plane (result SCIP_SEPARATED),
1565 * - tightening the LP primal feasibility tolerance and requesting to solve the LP again (result SCIP_SOLVELP),
1566 * - performing a branching (result SCIP_BRANCHED).
1567 *
1568 * Note that in case SCIP_CONSADDED, the added constraints must be created with flag initial=TRUE.
1569 *
1570 * However, the solution is not given as a SCIP_SOL* data structure.
1571 *
1572 * The value of a variable <code>var</code> in the LP solution can be accessed by calling
1573 * \code
1574 * SCIPgetVarSol(scip, var)
1575 * \endcode
1576 * or by
1577 * \code
1578 * SCIPgetSolVal(scip, NULL, var)
1579 * \endcode
1580 * By using the latter method, you can have a single local method to check a solution for feasibility by passing
1581 * the given <code>sol</code> to the CONSCHECK call and by passing a NULL pointer as <code>sol</code> to
1582 * the CONSENFOLP and CONSENFOPS calls.
1583 *
1584 *
1585 * @subsection CONSENFOPS
1586 *
1587 * The CONSENFOPS callback is similar to the CONSENFOLP callback, but deals with \em pseudo \em solutions instead
1588 * of LP solutions.
1589 *
1590 * If the LP was not solved at the current subproblem (either because the user did not want to solve it, or because
1591 * numerical difficulties in the LP solving process were detected) no LP solution is available.
1592 * In this situation, the pseudo solution is used instead.
1593 * In this solution, the variables are set to the local bound which is best with respect to the objective function.
1594 * You can think of the pseudo solution as solution to the LP relaxation with all constraints except the bounds
1595 * being removed.
1596 *
1597 * Like the ENFOLP callback, the ENFOPS callback has to check whether the pseudo solution satisfies all the constraints
1598 * of the constraint handler.
1599 * The pseudo solution can be accessed by the same methods as the LP solution (SCIP knows, if the LP was solved at the
1600 * current subproblem, and returns either the LP solution or the pseudo solution).
1601 *
1602 * Unlike the ENFOLP callback, the ENFOPS callback must not add cuts and cannot return the result SCIP_SEPARATED.
1603 * It is, however, possible to force the solving of the LP by returning the result SCIP_SOLVELP.
1604 * For example, the infeasibility of a linear constraint that contains continuous variables cannot be resolved,
1605 * if all integer variables in the constraint are already fixed.
1606 * In this case, the LP has to be solved in order to get a solution that satisfies the linear constraint.
1607 *
1608 * @subsection CONSENFORELAX
1609 *
1610 * The CONSENFORELAX callback is similar to the CONSENFOLP and CONSENFOPS callbacks, but deals with relaxation solutions.
1611 *
1612 * If the best bound computed by a relaxator that includes the whole LP is strictly better than the bound of the LP itself,
1613 * the corresponding relaxation solution will get enforced. Therefore the CONSENFORELAX callback will only be called for
1614 * solutions that satisfy all active LP-constraints.
1615 *
1616 * Like the ENFOLP and ENFOPS callbacks, the ENFORELAX callback has to check whether the solution given in sol satisfies
1617 * all the constraints of the constraint handler. Since the callback is only called for relaxators including the whole LP,
1618 * cuts may be added with a result of SCIP_SEPARATED, like in the ENFOLP callback. It is also possible to return
1619 * SCIP_SOLVELP if the relaxation solution is invalid for some reason and the LP should be solved instead.
1620 *
1621 * Note that the CONSENFORELAX callback is only relevant if relaxators are used. Since the basic distribution of the
1622 * SCIP Optimization Suite does not contain any relaxators, this callback can be ignored unless any relaxators are added
1623 * via user-plugins.
1624 *
1625 * @subsection CONSLOCK
1626 *
1627 * The CONSLOCK callback provides dual information for a single constraint.
1628 * It has to tell SCIP, which variables are existing in the given constraint, and in which way modifications of these
1629 * variables may affect the feasibility of the constraint.
1630 *
1631 * For each variable that is affected by the constraint, the callback should call SCIPaddVarLocks():
1632 * - If the constraint may become violated by decreasing the value of a variable, it should call
1633 * SCIPaddVarLocks(scip, var, nlockspos, nlocksneg), saying that rounding down is potentially rendering the
1634 * (positive) constraint infeasible and rounding up is potentially rendering the negation of the constraint
1635 * infeasible.
1636 * - If the constraint may become violated by increasing the value of a variable, it should call
1637 * SCIPaddVarLocks(scip, var, nlocksneg, nlockspos), saying that rounding up is potentially rendering the
1638 * constraint's negation infeasible and rounding down is potentially rendering the constraint itself
1639 * infeasible.
1640 * - If the constraint may become violated by changing the variable in any direction, it should call
1641 * SCIPaddVarLocks(scip, var, nlockspos + nlocksneg, nlockspos + nlocksneg).
1642 *
1643 * <b>Note:</b> You do not have to worry about nlockspos and nlocksneg. These integer values are given as
1644 * parameter of the CONSLOCK callback (see type_cons.h). Just use these variables in the above described
1645 * fashion <b>without</b> adding or subtracting anything to them. In case of the knapsack constraints this
1646 * method looks like this.
1647 *
1648 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsLockKnapsack}
1649 *
1650 * To give same more intuition, consider the linear constraint \f$3x -5y +2z \leq 7\f$ as an example.
1651 * The CONSLOCK callback method of the linear constraint handler should call
1652 * SCIPaddVarLocks(scip, x, nlocksneg, nlockspos), SCIPaddVarLocks(scip, y, nlockspos, nlocksneg),
1653 * and SCIPaddVarLocks(scip, z, nlocksneg, nlockspos) to tell SCIP, that rounding up of \f$x\f$
1654 * and \f$z\f$ and rounding down of \f$y\f$ can destroy the feasibility of the constraint, while rounding
1655 * down of \f$x\f$ and \f$z\f$ and rounding up of \f$y\f$ can destroy the feasibility of the
1656 * constraint's negation \f$3x -5y +2z > 7\f$.
1657 * \n
1658 * A linear constraint \f$2 \leq 3x -5y +2z \leq 7\f$ should call
1659 * SCIPaddVarLocks(scip, ..., nlockspos + nlocksneg, nlockspos + nlocksneg) on all variables,
1660 * since rounding in both directions of each variable can destroy both the feasibility of the
1661 * constraint and it's negation \f$3x -5y +2z < 2\f$ or \f$3x -5y +2z > 7\f$.
1662 *
1663 *
1664 * @section CONS_ADDITIONALCALLBACKS Additional Callback Methods
1665 *
1666 * The additional callback methods do not need to be implemented in every case, but provide useful functionality
1667 * for many applications. They can be added to your constraint handler via setter functions, see
1668 * \ref CONS_INTERFACE "here".
1669 *
1670 * @subsection CONSFREE
1671 *
1672 * If you are using constraint handler data, you have to implement this method in order to free the
1673 * constraint handler data. This can be done by the following procedure (which is taken from the
1674 * \ref cons_knapsack.h "knapsack constraint handler"):
1675 *
1676 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsFreeKnapsack}
1677 *
1678 * If you have allocated memory for fields in your constraint handler data, remember to free this memory
1679 * before freeing the constraint handler data itself.
1680 * If you are using the C++ wrapper class, this method is not available.
1681 * Instead, just use the destructor of your class to free the member variables of your class.
1682 *
1683 * @subsection CONSHDLRCOPY
1684 *
1685 * The CONSHDLRCOPY callback is executed when the SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
1686 * callback as <code>NULL</code> the user disables the inclusion of the specified constraint handler into all copied SCIP
1687 * instances. This may deteriorate the performance of primal heuristics solving sub-SCIPs, since these constitute only
1688 * relaxations of the original problem if constraint handlers are missing.
1689 *
1690 * A usual implementation just
1691 * calls the interface method which includes the constraint handler to the model. For example, this callback is
1692 * implemented for the \ref cons_knapsack.c "knapsack constraint handler" as follows:
1693 *
1694 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsCopyKnapsack}
1695 *
1696 * <b>Note:</b> If you implement this callback, take care when setting the valid pointer.
1697 *
1698 * A problem copy is called valid if it is valid in both the primal and the dual sense, i.e., if
1699 *
1700 * - it is a relaxation of the source problem
1701 * - it does not enlarge the feasible region.
1702 *
1703 * A constraint handler may choose to not copy a constraint and still declare the resulting copy as valid. It must ensure
1704 * the feasibility of any solution to the problem copy in the original (source) space.
1705 *
1706 * <b>Note:</b> If you implement this callback and the constraint handler needs constraints (see CONSHDLR_NEEDSCONS),
1707 * then you also need to implement the callback \ref CONSCOPY.
1708 *
1709 * @subsection CONSINIT
1710 *
1711 * The CONSINIT callback is executed after the problem is transformed.
1712 * The constraint handler may, e.g., use this call to replace the original variables in its constraints by transformed
1713 * variables, or to initialize its statistical constraint handler data.
1714 *
1715 * @subsection CONSEXIT
1716 *
1717 * The CONSEXIT callback is executed before the transformed problem is freed.
1718 * In this method, the constraint handler should free all resources that were allocated for the solving process.
1719 *
1720 * @subsection CONSINITPRE
1721 *
1722 * The CONSINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
1723 * The constraint handler may use this call to initialize its presolving data, or to modify its constraints
1724 * before the presolving process begins.
1725 * Necessary constraint modifications that have to be performed even if presolving is turned off should be done here
1726 * or in the presolving deinitialization call.
1727 *
1728 * @subsection CONSEXITPRE
1729 *
1730 * The CONSEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
1731 * The constraint handler may use this call e.g. to clean up its presolving data, or to finally modify its constraints
1732 * before the branch-and-bound process begins.
1733 * Necessary constraint modifications that have to be performed even if presolving is turned off should be done here
1734 * or in the presolving initialization call.
1735 * Besides necessary modifications and clean up, no time consuming operations should be done.
1736 *
1737 * @subsection CONSINITSOL
1738 *
1739 * The CONSINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
1740 * begin.
1741 * The constraint handler may use this call to initialize its branch-and-bound specific data.
1742 *
1743 * @subsection CONSEXITSOL
1744 *
1745 * The CONSEXITSOL callback is executed before the branch-and-bound process is freed.
1746 * The constraint handler should use this call to clean up its branch-and-bound data, in particular to release
1747 * all LP rows that it has created or captured.
1748 *
1749 * @subsection CONSDELETE
1750 *
1751 * The CONSDELETE callback is executed if a constraint should be freed.
1752 * You can think of it as the destructor of a single constraint.
1753 * In the callback, you have to free the given constraint data.
1754 * The CONSDELETE callback is therefore the counterpart of the SCIPcreateCons...() interface method and the CONSTRANS
1755 * method.
1756 *
1757 * @subsection CONSTRANS
1758 *
1759 * The CONSTRANS method is called for each constraint of the constraint handler, when the user starts the solving
1760 * process.
1761 * It has to copy the original constraint data of the constraint to the memory for the transformed problem.
1762 * You can think of it as a copy constructor for a single constraint.
1763 *
1764 * The original model is copied in order to protect it from transformations that are applied during the solving process,
1765 * in particular during preprocessing.
1766 * Preprocessing and solving always operates on the transformed problem.
1767 * If the solving process data are freed, the original data still exist and the user can, e.g., modify the problem and
1768 * restart the solving process.
1769 *
1770 * If you do not implement the CONSTRANS method, a transformed constraint is created with the same flags and the
1771 * same constraint data pointer.
1772 * That means, the transformed constraint points to the original constraint data.
1773 * This is okay, as long as the constraint data is not changed during the solving process.
1774 * If you want to implement preprocessing methods or other methods that modify the constraint data, you have to
1775 * implement the CONSTRANS method and create a copy of the constraint data.
1776 *
1777 * Here is an example, which is taken from the \ref cons_knapsack.h "knapsack constraint handler":
1778 *
1779 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsTransKnapsack}
1780 *
1781 * @subsection CONSINITLP
1782 *
1783 * The CONSINITLP callback is executed before the first LP relaxation is solved.
1784 * It should add the LP relaxations of all "initial" constraints to the LP. The method should scan the constraints
1785 * array for constraints that are marked initial via calls to SCIPconsIsInitial() and put the LP relaxation
1786 * of all initial constraints to the LP with calls to SCIPaddCut().
1787 *
1788 * @subsection CONSSEPALP
1789 *
1790 * The CONSSEPALP callback is executed during the price-and-cut loop of the subproblem processing.
1791 * It should try to generate cutting planes for the constraints of the constraint handler in order to separate
1792 * the current LP solution.
1793 * The method is called in the LP solution loop, which means that a valid LP solution exists.
1794 *
1795 * Usually, a separation callback searches and produces cuts, that are added with a call to SCIPaddCut().
1796 * If the cut should be remembered in the global cut pool, it may also call SCIPaddPoolCut().
1797 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
1798 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
1799 * However, the callback may also produce domain reductions or add other constraints.
1800 *
1801 * The CONSSEPALP callback has the following options:
1802 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1803 * - adding an additional constraint (result SCIP_CONSADDED)
1804 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1805 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
1806 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
1807 * (result SCIP_DIDNOTFIND)
1808 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
1809 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
1810 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
1811 *
1812 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1813 * CONSHDLR_SEPAFREQ, CONSHDLR_SEPAPRIORITY, and CONSHDLR_DELAYSEPA, which influence the behaviour of SCIP
1814 * calling CONSSEPALP.
1815 *
1816 * @subsection CONSSEPASOL
1817 *
1818 * The CONSSEPASOL callback is executed during separation loop on arbitrary primal solutions.
1819 * It should try to generate cutting planes for the constraints of the constraint handler in order to separate
1820 * the given primal solution.
1821 * The method is not called in the LP solution loop, which means that there is no valid LP solution.
1822 *
1823 * Usually, a separation callback searches and produces cuts, that are added with a call to SCIPaddCut().
1824 * If the cut should be remembered in the global cut pool, it may also call SCIPaddPoolCut().
1825 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
1826 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
1827 * However, the callback may also produce domain reductions or add other constraints.
1828 *
1829 * The CONSSEPASOL callback has the following options:
1830 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1831 * - adding an additional constraint (result SCIP_CONSADDED)
1832 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1833 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
1834 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
1835 * (result SCIP_DIDNOTFIND)
1836 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
1837 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
1838 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
1839 *
1840 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1841 * CONSHDLR_SEPAFREQ, CONSHDLR_SEPAPRIORITY, and CONSHDLR_DELAYSEPA, which influence the behaviour of SCIP
1842 * calling CONSSEPASOL.
1843 *
1844 * @subsection CONSPROP
1845 *
1846 * The CONSPROP callback is called during the subproblem processing.
1847 * It should propagate the constraints, which means that it should infer reductions in the variables' local bounds
1848 * from the current local bounds.
1849 * This technique, which is the main workhorse of constraint programming, is called "node preprocessing" in the
1850 * Integer Programming community.
1851 *
1852 * The CONSPROP callback has the following options:
1853 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1854 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1855 * - stating that the propagator searched, but did not find domain reductions, cutting planes, or cut constraints
1856 * (result SCIP_DIDNOTFIND)
1857 * - stating that the propagator was skipped (result SCIP_DIDNOTRUN)
1858 * - stating that the propagator was skipped, but should be called again (result SCIP_DELAYED)
1859 *
1860 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1861 * CONSHDLR_PROPFREQ, CONSHDLR_DELAYPROP, and CONSHDLR_PROP_TIMING, which influence the behaviour of SCIP
1862 * calling CONSPROP.
1863 *
1864 * @subsection CONSRESPROP
1865 *
1866 * If the constraint handler should support \ref CONF "conflict analysis", it has to supply a CONSRESPROP method.
1867 * It also should call SCIPinferVarLbCons() or SCIPinferVarUbCons() in domain propagation instead of SCIPchgVarLb() or
1868 * SCIPchgVarUb() in order to deduce bound changes on variables.
1869 * In the SCIPinferVarLbCons() and SCIPinferVarUbCons() calls, the handler provides the constraint that deduced the
1870 * variable's bound change, and an integer value <code>inferinfo</code> that can be arbitrarily chosen.
1871 *
1872 * The propagation conflict resolving method CONSRESPROP must then be implemented to provide the "reasons" for the bound
1873 * changes, i.e., the bounds of variables at the time of the propagation, which forced the constraint to set the
1874 * conflict variable's bound to its current value. It can use the <code>inferinfo</code> tag to identify its own propagation rule
1875 * and thus identify the "reason" bounds. The bounds that form the reason of the assignment must then be provided by
1876 * calls to SCIPaddConflictLb() and SCIPaddConflictUb() in the propagation conflict resolving method.
1877 *
1878 * <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
1879 * need more information to efficiently infer the original propagation steps that lead to the conflict. This would,
1880 * however, require too much space. In the extreme, the original propagation steps have to be repeated.
1881 *
1882 * 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
1883 * 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
1884 * variables are 0.0). It uses <code>SCIPinferVarLbCons(scip, z, 1.0, c, 0)</code> to apply this assignment (an
1885 * inference information tag is not needed by the constraint handler and is set to 0). In the conflict analysis, the
1886 * constraint handler may be asked to resolve the lower bound change on \f$z\f$ with constraint \f$c\f$, that was
1887 * applied at a time given by a bound change index "bdchgidx". With a call to <code>SCIPvarGetLbAtIndex(z,
1888 * bdchgidx)</code>, the handler can find out, that the lower bound of variable \f$z\f$ was set to 1.0 at the given
1889 * point of time, and should call <code>SCIPaddConflictUb(scip, x, bdchgidx)</code> and <code>SCIPaddConflictUb(scip, y,
1890 * 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
1891 * the deduction of the lower bound of \f$z\f$.
1892 *
1893 * If conflict analysis should not be supported, the method has to set the result code to SCIP_DIDNOTFIND. Although
1894 * this is a viable approach to circumvent the implementation of the usually rather complex conflict resolving method, it
1895 * will make the conflict analysis less effective. We suggest to first omit the conflict resolving method and check how
1896 * effective the \ref CONSPROP "propagation method" is. If it produces a lot of propagations for your application, you definitely should
1897 * consider implementing the conflict resolving method.
1898 *
1899 * @subsection CONSPRESOL
1900 *
1901 * The CONSPRESOL callback is called during preprocessing.
1902 * It should try to tighten the domains of the variables, tighten the coefficients of the constraints of the constraint
1903 * handler, delete redundant constraints, aggregate and fix variables if possible, and upgrade constraints to more
1904 * specific types.
1905 *
1906 * If the CONSPRESOL callback applies changes to the constraint data, you also have to implement the \ref CONSTRANS callback
1907 * in order to copy the constraint data to the transformed problem space and protect the original problem from the
1908 * preprocessing changes.
1909 *
1910 * To inform SCIP that the presolving method found a reduction the result pointer has to be set in a proper way.
1911 * The following options are possible:
1912 *
1913 * - SCIP_UNBOUNDED : at least one variable is not bounded by any constraint in objective direction
1914 * - SCIP_CUTOFF : at least one constraint is infeasible in the variable's bounds
1915 * - SCIP_SUCCESS : the presolver found a reduction
1916 * - SCIP_DIDNOTFIND : the presolver searched, but did not find a presolving change
1917 * - SCIP_DIDNOTRUN : the presolver was skipped
1918 * - SCIP_DELAYED : the presolver was skipped, but should be called again
1919 *
1920 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1921 * CONSHDLR_PRESOLTIMING and CONSHDLR_MAXPREROUNDS, which influence the behaviour of SCIP
1922 * calling CONSPRESOL.
1923 *
1924 * @subsection CONSACTIVE
1925 *
1926 * The CONSACTIVE callback method is called each time a constraint of the constraint handler is activated.
1927 * For example, if a constraint is added locally to a subproblem, the CONSACTIVE callback is called whenever the
1928 * search enters the subtree where the constraint exists.
1929 *
1930 * @subsection CONSDEACTIVE
1931 *
1932 * The CONSDEACTIVE callback method is called each time a constraint of the constraint handler is deactivated.
1933 * For example, if a constraint is added locally to a subproblem, the CONSDEACTIVE callback is called whenever the
1934 * search leaves the subtree where the constraint exists.
1935 *
1936 * @subsection CONSENABLE
1937 *
1938 * The CONSENABLE callback method is called each time a constraint of the constraint handler is enabled.
1939 * Constraints might be active without being enabled. In this case, only the feasibility checks are executed,
1940 * but domain propagation and separation is skipped.
1941 *
1942 * @subsection CONSDISABLE
1943 *
1944 * The CONSDISABLE callback method is called each time a constraint of the constraint handler is disabled.
1945 *
1946 * @subsection CONSPRINT
1947 *
1948 * The CONSPRINT callback method is called, when the user asks SCIP to display the problem to the screen
1949 * or save the problem into a file. This is, however, only the case if the user requested the CIP format.
1950 * For more details about reading and writing with SCIP we refer to the \ref READER "file readers". In this
1951 * callback method the constraint handler should display the data of the constraint in an appropriate form.
1952 * The output format that is defined by the CONSPRINT callbacks is called CIP format.
1953 * In later versions of SCIP, the constraint handlers should also be able to parse (i.e., read) constraints
1954 * which are given in CIP format.
1955 *
1956 * @subsection CONSCOPY
1957 *
1958 * The CONSCOPY callback method is used whenever constraints should be copied from one SCIP instance into another SCIP
1959 * instance. This method comes with the necessary parameters to do so, most importantly with a mapping of the variables of the
1960 * source SCIP instance to the corresponding variables of the target SCIP instance, and a mapping for the constraints
1961 * in the same way. For a complete list of all arguments of this callback method see type_cons.h.
1962 *
1963 * To get the corresponding target variable of a given source variable, you can use the variable map directly:
1964 *
1965 * \code
1966 * targetvar = (SCIP_VAR*) SCIPhashmapGetImage(varmap, sourcevar);
1967 * \endcode
1968 *
1969 * We recommend, however, to use the method SCIPgetVarCopy() which gets besides others the variable map and the constraint map as input
1970 * and returns the requested target variable. The advantage of using SCIPgetVarCopy() is that in the case
1971 * the required variable does not yet exist, it is created and added to the copy automatically:
1972 *
1973 * \code
1974 * SCIP_CALL( SCIPgetVarCopy(sourcescip, scip, sourcevar, &targetvar, varmap, consmap, global) );
1975 * \endcode
1976 *
1977 * Finally, the result pointer <code>valid</code> has to be set to TRUE if (and only if!) the copy process was successful.
1978 *
1979 * <b>Note:</b> Be careful when setting the valid pointer.
1980 * A problem copy is called valid if it is valid in both the primal and the dual sense, i.e., if
1981 *
1982 * - it is a relaxation of the source problem
1983 * - it does not enlarge the feasible region.
1984 *
1985 * A constraint handler may choose to not copy a constraint and still declare the resulting copy as valid. Therefore, it must ensure
1986 * the feasibility of any solution to the problem copy in the original (source) space.
1987 *
1988 * For an example implementation we refer to cons_linear.h. Additional documentation and the complete list of all
1989 * parameters can be found in the file in type_cons.h.
1990 *
1991 * @subsection CONSPARSE
1992 *
1993 * This method is the counter part to CONSPRINT. The ideal idea is that a constraint handler is able to parse the output
1994 * which it generated via the CONSPRINT method and creates the corresponding constraint. If the parsing was successfully
1995 * the result pointer success should be set to TRUE. An example implementation can be found in the \ref cons_linear.h
1996 * "linear constraint handler".
1997 *
1998 * @subsection CONSDELVARS
1999 *
2000 * This method should iterate over the given constraints and delete all variables that were marked for deletion by SCIPdelVar().
2001 * Variable deletion is especially interesting for branch-cut-and-price applications. If your constraint handler allows
2002 * the addition of variables during the solving process (see "modifiable" attribute of constraints), then you might also want to
2003 * implement this callback. This would allow you to not only create variables during solving, but also remove them dynamically
2004 * from the problem to reduce memory consumption in case they are no longer necessary.
2005 * During presolving, SCIP may also find that some variables are not needed anymore and then try
2006 * to delete them. Thus, if you do not implement this callback, the constraint handler should capture its variables via
2007 * SCIPcaptureVar() to prevent SCIP from erroneously deleting them.
2008 *
2009 * Additional documentation and the complete list of all parameters can be found in the file type_cons.h.
2010 *
2011 * @subsection CONSGETVARS
2012 *
2013 * The CONSGETVARS callback of a constraint handler can be implemented to give access to the constraint variables
2014 * as array, independently from the internal data structure of the constraint. The buffer array
2015 * is already passed, together with its length. Consider implementing @ref CONSGETNVARS, too, to have
2016 * information about the number of variables in this constraint.
2017 *
2018 * @subsection CONSGETNVARS
2019 *
2020 * This callback can be implemented to return the number of variables involved into a particular constraint.
2021 * In order to have access to the variable pointers, consider implementing @ref CONSGETVARS.
2022 *
2023 * @refsnippet{src/scip/cons_linear.c,Callback for the number of variables}
2024 *
2025 * @subsection CONSGETDIVEBDCHGS
2026 *
2027 * This callback is used inside the various diving heuristics of SCIP and does not affect the normal branching
2028 * of the actual search.
2029 * The constraint handler can provide this callback to render a current working solution (even more) infeasible by
2030 * suggesting one or several variable bound changes.
2031 *
2032 * @section CONS_FURTHERINFO Further documentation
2033 *
2034 * Further documentation can be found in @ref type_cons.h for callback descriptions and a complete
2035 * list of all callback parameters, or in @ref scip.h
2036 * for globally available functions.
2037 */
2038
2039/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2040
2041/**@page PRICER How to add variable pricers
2042 *
2043 * A pricer performs the dynamic generation of new variables in a column generation algorithm.
2044 * It is an algorithmic representation of a (usually exponential) number of variables.
2045 * The \ref PRICERREDCOST and \ref PRICERFARKAS methods are called after each LP solve to generate additional
2046 * variables which may improve the objective value or decrease the LP infeasibility, respectively.
2047 * \n
2048 * A complete list of all pricers contained in this release can be found \ref PRICERS "here".
2049 *
2050 * If the pricer finds one or more variables with negative reduced costs or negative Farkas value, it should
2051 * call SCIPcreateVar() and SCIPaddPricedVar() to create and add the variable to the problem. Additionally,
2052 * the pricer has to add the variable to all constraints in which it appears. Therefore, a pricer needs to
2053 * know the constraints of the model and their meaning. Note that all constraints for which additional variables
2054 * are generated by a pricer have to be flagged as "modifiable" in the SCIPcreateCons() call.
2055 *
2056 * We now explain how users can add their own pricers.
2057 * For example, look into the variable pricer for the binpacking problem (examples/Binpacking/src/pricer_binpacking.c) of the
2058 * Binpacking example project.
2059 * The example is written in C. C++ users can easily adapt the code by using the scip::scip::ObjPricer wrapper base class and
2060 * implement the scip_...() virtual methods instead of the SCIP_DECL_PRICER... callback methods.
2061 *
2062 * Additional documentation for the callback methods of a pricer can be found in the file
2063 * type_pricer.h.
2064 *
2065 * Notice that if your pricer cannot cope with variable bounds other than 0 and infinity, you have to mark
2066 * all constraints containing priced variables as modifiable, and you may have to disable reduced cost
2067 * strengthening by setting propagating/rootredcost/freq to -1.
2068 *
2069 * Here is what you have to do to implement a pricer:
2070 * -# Copy the template files src/scip/pricer_xyz.c and src/scip/pricer_xyz.h into files "pricer_mypricer.c"
2071 * and "pricer_mypricer.h".
2072 * \n
2073 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2074 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2075 * -# Use `SCIPincludePricerMypricer()` in order to include the pricer into your SCIP instance,
2076 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2077 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2078 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypricer".
2079 * -# Adjust the properties of the pricer (see \ref PRICER_PROPERTIES).
2080 * -# Define the pricer data (see \ref PRICER_DATA). This is optional.
2081 * -# Implement the interface methods (see \ref PRICER_INTERFACE).
2082 * -# Implement the fundamental callback methods (see \ref PRICER_FUNDAMENTALCALLBACKS).
2083 * -# Implement the additional callback methods (see \ref PRICER_ADDITIONALCALLBACKS). This is optional.
2084 *
2085 *
2086 * @section PRICER_PROPERTIES Properties of a Pricer
2087 *
2088 * At the top of the new file "pricer_mypricer.c" you can find the pricer properties.
2089 * These are given as compiler defines.
2090 * In the C++ wrapper class, you have to provide the pricer properties by calling the constructor
2091 * of the abstract base class scip::ObjPricer from within your constructor.
2092 * The properties you have to set have the following meaning:
2093 *
2094 * \par PRICER_NAME: the name of the pricer.
2095 * This name is used in the interactive shell to address the pricer.
2096 * Additionally, if you are searching for a pricer with SCIPfindPricer(), this name is looked up.
2097 * Names have to be unique: no two pricers may have the same name.
2098 *
2099 * \par PRICER_DESC: the description of the pricer.
2100 * This string is printed as a description of the pricer in the interactive shell.
2101 *
2102 * \par PRICER_PRIORITY: the priority of the pricer.
2103 * In each pricing round during the price-and-cut loop of the subproblem processing, the included pricers are
2104 * called in a predefined order, which is given by the priorities of the pricers.
2105 * The higher the priority, the earlier the pricer is called.
2106 * Usually, you will have only one pricer in your application and the priority is therefore irrelevant.
2107 *
2108 * \par PRICER_DELAY: the default for whether the pricer should be delayed, if other variables with negative reduced
2109 * costs have already been found in the current pricing round.
2110 * Variables may be declared to be "removable" in the SCIPcreateVar() call. This means that SCIP may remove the variable
2111 * from the LP if it was inactive (i.e., sitting at zero) for a number of LP solves. Nevertheless, after the removal of the
2112 * column from the LP, the variable still exists, and SCIP can calculate reduced costs and add it to the LP again if
2113 * necessary.
2114 * \n
2115 * If the PRICER_DELAY flag is set to TRUE (which is the common setting), all those existing variables with negative reduced costs
2116 * are added to the LP, and the LP is resolved before the pricer is called. Thus, the pricer can assume that all existing variables
2117 * have non-negative reduced costs if the \ref PRICERREDCOST method is called or non-positive Farkas value if the \ref PRICERFARKAS
2118 * method is called.
2119 * \n
2120 * In some applications, this inner pricing loop on the already existing variables can significantly slow down the solving process,
2121 * since it may lead to the addition of only very few variables in each pricing round. If this is an issue in your application,
2122 * you should consider setting the PRICER_DELAY flag to FALSE. You must, however, be aware of the fact that there may be already
2123 * existing variables with negative reduced costs. For example, this may lead to the issue that your pricer generates the same
2124 * variable twice. In some models, this is not critical because an optimal solution would choose only one of the two identical
2125 * variables anyway, but for other models this can lead to wrong results because the duplication of a variable essentially doubles
2126 * the upper bound of the variable.
2127 *
2128 *
2129 * @section PRICER_DATA Pricer Data
2130 *
2131 * Below the header "Data structures" you can find a struct which is called "struct SCIP_PricerData".
2132 * In this data structure, you can store the data of your pricer. For example, it may be convenient to store pointers to the
2133 * constraints of the problem instance here, because the pricer has to add variables to those constraints.
2134 * If you are using C++, you can add pricer data, as usual, as object variables to your class.
2135 * \n
2136 * Defining pricer data is optional. You can leave the struct empty.
2137 *
2138 *
2139 * @section PRICER_INTERFACE Interface Methods
2140 *
2141 * At the bottom of "pricer_mypricer.c" you can find the interface method SCIPincludePricerMypricer(), which also appears in "pricer_mypricer.h".
2142 * 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
2143 * be generated by this pricer.
2144 *
2145 * This method only has to be adjusted slightly.
2146 * It is responsible for notifying SCIP of the presence of the pricer. For this, you can either call SCIPincludePricer(),
2147 * or SCIPincludePricerBasic() since SCIP version 3.0. In the latter variant, \ref PRICER_ADDITIONALCALLBACKS "additional callbacks"
2148 * must be added via setter functions as, e.g., SCIPsetPricerCopy(). We recommend this latter variant because
2149 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2150 * variant must be manually adjusted with every SCIP release containing new callbacks for pricers in order to compile.
2151 *
2152 *
2153 * In addition, the pricer has to be activated before the solution process starts, like it is done
2154 * in the pricer of the Coloring application (applications/Coloring/src/reader_col.c) by calling
2155 * \code
2156 * SCIP_CALL( SCIPactivatePricer(scip, SCIPfindPricer(scip, "coloring")) );
2157 * \endcode
2158 *
2159 * If you are using pricer data, you have to allocate the memory for the data at this point.
2160 * You can do this by calling:
2161 * \code
2162 * SCIP_CALL( SCIPallocBlockMemory(scip, &pricerdata) );
2163 * \endcode
2164 * You also have to initialize the fields in struct SCIP_PricerData afterwards.
2165 *
2166 * You may also add user parameters for your pricer, see the method SCIPincludePricerColoring() in the pricer of the Coloring application
2167 * for an example of how to add user parameters.
2168 *
2169 *
2170 * @section PRICER_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Pricer
2171 *
2172 * The fundamental callback methods have to be implemented in order to obtain an operational algorithm.
2173 * They are passed together with the pricer itself to SCIP using SCIPincludePricer() or SCIPincludePricerBasic(),
2174 * see @ref PRICER_INTERFACE.
2175 *
2176 * In the case of a pricer, there are two fundamental callback methods, namely the @ref PRICERREDCOST and the
2177 * @ref PRICERFARKAS callbacks, which both search for new variables and add them to the problem.
2178 * These methods have to be implemented for every pricer; the other callback methods are optional.
2179 * In the C++ wrapper class scip::ObjPricer, the scip_redcost() method (which corresponds to the PRICERREDCOST callback)
2180 * is a virtual abstract member function. You have to implement it in order to be able to construct an object of your
2181 * pricer class.
2182 *
2183 * Additional documentation for the callback methods can be found in type_pricer.h.
2184 *
2185 * @subsection PRICERREDCOST
2186 *
2187 * The PRICERREDCOST callback is called inside the price-and-cut loop of the subproblem solving process if the current LP relaxation
2188 * is feasible.
2189 * It should search for additional variables that can contribute to improve the current LP's solution value.
2190 * In standard branch-and-price, these are variables with negative dual feasibility, that is negative
2191 * reduced costs for non-negative variables, positive reduced costs for non-positive variables,
2192 * and non-zero reduced costs for variables that can be negative and positive.
2193 *
2194 * Whenever the pricer finds a variable with negative dual feasibility, it should call SCIPcreateVar()
2195 * and SCIPaddPricedVar() to add the variable to the problem. Furthermore, it should call the appropriate
2196 * methods of the constraint handlers to add the necessary variable entries to the constraints, see pub_cons.h.
2197 *
2198 * In the usual case that the pricer either adds a new variable or ensures that there are no further variables with negative dual feasibility,
2199 * the result pointer should be set to SCIP_SUCCESS. Only if the pricer aborts pricing without creating a new variable, but
2200 * there might exist additional variables with negative dual feasibility, the result pointer should be set to SCIP_DIDNOTRUN.
2201 * In this case, which sometimes is referred to as "early branching", the LP solution will not be used as a lower bound.
2202 * The pricer can, however, store a valid lower bound in the <code>lowerbound</code> pointer.
2203 *
2204 * Pricers usually need the dual LP solution as input for the pricing algorithm.
2205 * Since SCIP does not know the semantics of the individual constraints in the problem, the dual solution
2206 * has to be provided by the constraint handlers.
2207 * For example, the \ref cons_setppc.h "setppc constraint handler", which deals with set partitioning, packing, and covering constraints, provides
2208 * the method SCIPgetDualsolSetppc() to access the dual solution value for a single constraint.
2209 * Similarly, the dual solution of a linear constraint can be queried with the method SCIPgetDualsolLinear() of cons_linear.h.
2210 * The reduced costs of the existing variables can be accessed with the method SCIPgetVarRedcost().
2211 *
2212 * @subsection PRICERFARKAS
2213 *
2214 * If the current LP relaxation is infeasible, it is the task of the pricer to generate additional variables that can
2215 * potentially render the LP feasible again. In standard branch-and-price, these are variables with positive Farkas values,
2216 * and the PRICERFARKAS method should identify those variables.
2217 *
2218 * If the LP was proven to be infeasible, we have an infeasibility proof by the dual Farkas multipliers \f$y\f$.
2219 * 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
2220 * by the sides of the LP rows and the sign of \f$y\f$:
2221 * - if \f$y_i\f$ is positive, \f$b_i\f$ is the left hand side of the row,
2222 * - if \f$y_i\f$ is negative, \f$b_i\f$ is the right hand side of the row.
2223 *
2224 * \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$,
2225 * especially by the (for this inequality least infeasible solution) \f$x'\f$ defined by
2226 * - \f$x'_i := ub_i\f$, if \f$y^T A_i \ge 0\f$
2227 * - \f$x'_i := lb_i\f$, if \f$y^T A_i < 0\f$.
2228 * 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$.
2229 *
2230 * To apply Farkas pricing, the pricer needs to know the Farkas values of the constraints. Like the dual solution values for
2231 * feasible LP solutions, the dual Farkas values for infeasible solutions can be obtained by constraint handler interface
2232 * methods such as the SCIPgetDualfarkasLinear() method of the linear constraint handler.
2233 * The Farkas values for the bounds of the variables can be accessed with SCIPgetVarFarkasCoef().
2234 *
2235 * It is useful to note that Farkas pricing is the same as the regular pricing with a zero objective function.
2236 * Therefore, a typical implementation of a pricer would consist of a generic pricing algorithm that gets a dual solution and an
2237 * objective function vector as input and generates variables by calling SCIPcreateVar() and SCIPaddPricedVar().
2238 * The PRICERREDCOST callback would call this function with the regular objective function and the regular dual solution vector,
2239 * while the PRICERFARKAS callback would call this function with a zero objective function and the Farkas vector.
2240 * From a practical point of view, it is usually the simplest approach to provide just one Boolean flag to the generic pricing
2241 * algorithm in order to identify whether it is reduced cost or Farkas pricing. Then, the algorithm would just call the appropriate
2242 * methods to access the dual solution or objective function, depending on the Boolean flag.
2243 *
2244 * @section PRICER_ADDITIONALCALLBACKS Additional Callback Methods of a Pricer
2245 *
2246 * The additional callback methods do not need to be implemented in every case.
2247 * However, some of them have to be implemented for most applications. They can either be passed directly with
2248 * SCIPincludePricer() to SCIP or via specific <b>setter functions</b> after a call of SCIPincludePricerBasic(),
2249 * see also @ref PRICER_INTERFACE.
2250 *
2251 * @subsection PRICERFREE
2252 *
2253 * If you are using pricer data, you have to implement this method in order to free the pricer data.
2254 * This can be done by the procedure described in stp/src/pricer_stp.c,
2255 * see https://scipjack.zib.de/.
2256 *
2257 * If you have allocated memory for fields in your pricer data, remember to free this memory
2258 * before freeing the pricer data itself.
2259 * If you are using the C++ wrapper class, this method is not available.
2260 * Instead, just use the destructor of your class to free the member variables of your class.
2261 *
2262 * @subsection PRICERCOPY
2263 *
2264 * The PRICERCOPY callback is executed when the SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
2265 * callback as <code>NULL</code> the user disables the inclusion of the pricer into all copied SCIP
2266 * instances. This means that primal heuristics will work on a sub-SCIP that contains only a part of the variables
2267 * and no variables are priced in during the solving process of the sub-SCIP. Therefore, primal solutions found in the
2268 * copied problem are typically still valid for the original problem and used for its solving process,
2269 * but dual reductions cannot be transferred to the original problem.
2270 *
2271 * <b>Note:</b> If you implement this callback, be careful when setting the valid pointer. The valid pointer should be
2272 * set to TRUE if (and only if!) you can make sure that all necessary data of the pricer are copied
2273 * correctly. If the complete problem is validly copied, i.e. if the copy methods of all problem defining plugins
2274 * (constraint handlers and pricers) return <code>*valid = TRUE</code>, then dual reductions found for the copied problem can be
2275 * transferred to the original SCIP instance. Thus, if the valid pointer is wrongly set to TRUE, it might happen that
2276 * optimal solutions are cut off.
2277 *
2278 * @subsection PRICERINIT
2279 *
2280 * The PRICERINIT callback is executed after the problem is transformed.
2281 * The pricer may, e.g., use this call to replace the original constraints stored in its pricer data by transformed
2282 * constraints, or to initialize other elements of its pricer data.
2283 *
2284 * @subsection PRICEREXIT
2285 *
2286 * The PRICEREXIT callback is executed before the transformed problem is freed.
2287 * In this method, the pricer should free all resources that have been allocated for the solving process in PRICERINIT.
2288 *
2289 * @subsection PRICERINITSOL
2290 *
2291 * The PRICERINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to begin.
2292 * The pricer may use this call to initialize its branch-and-bound specific data.
2293 *
2294 * @subsection PRICEREXITSOL
2295 *
2296 * The PRICEREXITSOL callback is executed before the branch-and-bound process is freed.
2297 * The pricer should use this call to clean up its branch-and-bound data, which was allocated in PRICERINITSOL.
2298 *
2299 * @section PRICER_REMARKS Further remarks
2300 *
2301 * 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".
2302 * Otherwise, SCIP will use its default branching rules, if necessary (which all branch on variables). This
2303 * could disturb the pricing problem or branching might not even be possible, e.g., if all variables created thus far have already been fixed.
2304 *
2305 * Note that if the original problem is a maximization problem, SCIP will transform the problem into a minimization
2306 * problem by multiplying the objective function by -1. The pricer has to take care of this by multiplying
2307 * the original objective function value of all variables created during the solving process by -1.
2308 *
2309 * In some cases, bounds on variables are implicitly enforced by constraints of the problem and the objective function.
2310 * 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
2311 * care about the corresponding dual values.
2312 * We call these bounds lazy bounds, they may be set by SCIPchgVarLbLazy() and SCIPchgVarUbLazy() for upper or lower bounds, respectively.
2313 * If the lazy bound equals the local bound, the corresponding bound is not put into the LP.
2314 * In diving mode, lazy bounds are explicitly put into the LP, because changing the objective (which is only possible in diving)
2315 * might reverse the implicitly given bounds. When diving is finished, the bounds are again removed from the LP.
2316 */
2317
2318/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2319
2320/**@page PRESOL How to add presolvers
2321 *
2322 * Presolvers are used to reduce the size of the model by removing irrelevant information like redundant constraints,
2323 * to strengthen the LP relaxation by exploiting integrality information, and to extract useful information in the
2324 * presolving step.
2325 * Constraint based presolving is done in the CONSPRESOL callback methods of the constraint handlers, see \ref CONSPRESOL.
2326 * Some propagation steps can already be applied in presolving via the PROPRESOL callback methods of propagators, see \ref PROPPRESOL.
2327 * The presolver plugins complement these by additional, usually optimality based, presolving reductions.
2328 * \n
2329 * A complete list of all presolvers contained in this release can be found \ref PRESOLVERS "here".
2330 *
2331 * We now explain how users can add their own presolvers.
2332 * Take the trivial presolver (src/scip/presol_trivial.c) as an example.
2333 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjPresol wrapper
2334 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_PRESOL... callback methods.
2335 *
2336 * Additional documentation for the callback methods of a presolver, in particular for their input parameters,
2337 * can be found in the file type_presol.h.
2338 *
2339 * Here is what you have to do to implement a presolver:
2340 * -# Copy the template files src/scip/presol_xyz.c and src/scip/presol_xyz.h into files named "presol_mypresolver.c"
2341 * and "presol_mypresolver.h".
2342 * \n
2343 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2344 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2345 * -# Use `SCIPincludePresolMypresolver()` in order to include the presolver into your SCIP instance,
2346 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2347 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2348 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypresolver".
2349 * -# Adjust the properties of the presolver (see \ref PRESOL_PROPERTIES).
2350 * -# Define the presolver data (see \ref PRESOL_DATA). This is optional.
2351 * -# Implement the interface methods (see \ref PRESOL_INTERFACE).
2352 * -# Implement the fundamental callback methods (see \ref PRESOL_FUNDAMENTALCALLBACKS).
2353 * -# Implement the additional callback methods (see \ref PRESOL_ADDITIONALCALLBACKS). This is optional.
2354 *
2355 *
2356 * @section PRESOL_PROPERTIES Properties of a Presolver
2357 *
2358 * At the top of the new file "presol_mypresolver.c", you can find the presolver properties.
2359 * These are given as compiler defines.
2360 * In the C++ wrapper class, you have to provide the presolver properties by calling the constructor
2361 * of the abstract base class scip::ObjPresol from within your constructor.
2362 * The properties you have to set have the following meaning:
2363 *
2364 * \par PRESOL_NAME: the name of the presolver.
2365 * This name is used in the interactive shell to address the presolver.
2366 * Additionally, if you are searching for a presolver with SCIPfindPresol(), this name is looked up.
2367 * Names have to be <b>unique</b>: no two presolvers may have the same name.
2368 *
2369 * \par PRESOL_DESC: the description of the presolver.
2370 * This string is printed as a description of the presolver in the interactive shell.
2371 *
2372 * \par PRESOL_TIMING: the default timing of the presolver.
2373 * There are three presolving timings: FAST, MEDIUM, and EXHAUSTIVE.
2374 * Every presolving round starts with the FAST presolvers. MEDIUM presolvers are only called, if FAST presolvers did not find
2375 * enough reductions in this round so far, and EXHAUSTIVE presolving steps are only performed if all presolvers called before
2376 * in this round were unsuccessful.
2377 * Presolvers should be assigned a timing based on how expensive they are, e.g., presolvers that provide fast algorithms that
2378 * usually have a high impact (i.e., remove lots of variables or tighten bounds of many variables) should have a timing FAST.
2379 * If a presolver implements different algorithms of different complexity, it may also get multiple timings and check the timing
2380 * internally in the \ref PRESOLEXEC callback to decide which algorithms to run.
2381 *
2382 * \par PRESOL_PRIORITY: the priority of the presolver.
2383 * Within a presolving round, when calling all presolvers and presolving methods of propagators and constraint handlers
2384 * with a given timing, those are called in
2385 * a predefined order, which is given by the priorities of the presolvers and the check priorities of the
2386 * constraint handlers, see \ref CONS_PROPERTIES.
2387 * First, the presolvers with non-negative priority are called in the order of decreasing priority.
2388 * Next, the presolving methods of the different constraint handlers are called in the order of decreasing check
2389 * priority.
2390 * Finally, the presolvers with negative priority are called in the order of decreasing priority.
2391 * \n
2392 * Again, presolvers that provide fast algorithms that usually have a high impact (i.e., remove lots of variables or tighten
2393 * bounds of many variables) should have a high priority.
2394 * An easy way to list the timings and
2395 * priorities of all presolvers, propagators, and constraint handlers is to type "display presolvers", "display propagators",
2396 * and "display conshdlrs" in the interactive shell of SCIP.
2397 *
2398 * \par PRESOL_MAXROUNDS: the default maximal number of rounds the presolver participates in.
2399 * The presolving is conducted in rounds: the presolvers and presolving methods of the constraint handlers
2400 * are called iteratively until no more reductions have been found or some other abort criterion applies.
2401 * The "maxrounds" parameter of a presolver imposes a limit on the number of presolving rounds in which the
2402 * presolver is called. The PRESOL_MAXROUNDS property specifies the default value for this parameter.
2403 * A value of -1 represents an unlimited number of rounds.
2404 *
2405 *
2406 * @section PRESOL_DATA Presolver Data
2407 *
2408 * Below the header "Data structures" you can find a struct which is called "struct SCIP_PresolData".
2409 * In this data structure, you can store the data of your presolver. For example, you should store the adjustable parameters
2410 * of the presolver in this data structure.
2411 * If you are using C++, you can add presolver data as usual as object variables to your class.
2412 * \n
2413 * Defining presolver data is optional. You can leave this struct empty.
2414 *
2415 *
2416 * @section PRESOL_INTERFACE Interface Methods
2417 *
2418 * At the bottom of "presol_mypresolver.c", you can find the interface method SCIPincludePresolMypresolver(),
2419 * which also appears in "presol_mypresolver.h"
2420 * SCIPincludePresolMypresolver() is called by the user, if (s)he wants to include the presolver,
2421 * i.e., if (s)he wants to use the presolver in his/her application.
2422 *
2423 * This method only has to be adjusted slightly.
2424 * It is responsible for notifying SCIP of the presence of the presolver. For this, you can either call SCIPincludePresol(),
2425 * or SCIPincludePresolBasic() since SCIP version 3.0. In the latter variant, \ref PRESOL_ADDITIONALCALLBACKS "additional callbacks"
2426 * must be added via setter functions as, e.g., SCIPsetPresolCopy(). We recommend this latter variant because
2427 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2428 * variant must be manually adjusted with every SCIP release containing new callbacks for presolvers in order to compile.
2429 *
2430 * If you are using presolver data, you have to allocate the memory for the data at this point.
2431 * You can do this by calling:
2432 * \code
2433 * SCIP_CALL( SCIPallocBlockMemory(scip, &presoldata) );
2434 * \endcode
2435 * You also have to initialize the fields in struct SCIP_PresolData afterwards. For freeing the
2436 * presolver data, see \ref PRESOLFREE.
2437 *
2438 * You may also add user parameters for your presolver, see \ref PARAM for how to add user parameters and
2439 * the method SCIPincludePresolTrivial() in src/scip/presol_trivial.c for an example.
2440 *
2441 *
2442 * @section PRESOL_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Presolver
2443 *
2444 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2445 * an operational algorithm.
2446 * They are passed together with the presolver itself to SCIP using SCIPincludePresol() or SCIPincludePresolBasic(),
2447 * see @ref PRESOL_INTERFACE.
2448 *
2449 * Presolver plugins have only one fundamental callback method, namely the @ref PRESOLEXEC method.
2450 * This method has to be implemented for every presolver; the other callback methods are optional.
2451 * In the C++ wrapper class scip::ObjPresol, the scip_exec() method (which corresponds to the PRESOLEXEC callback) is a virtual
2452 * abstract member function.
2453 * You have to implement it in order to be able to construct an object of your presolver class.
2454 *
2455 * Additional documentation for the callback methods, in particular to their input parameters,
2456 * can be found in type_presol.h.
2457 *
2458 * @subsection PRESOLEXEC
2459 *
2460 * The PRESOLEXEC callback is called inside the presolving loop and should perform the actual presolving reductions.
2461 * It should inspect the problem instance at hand and simplify it by tightening bounds of variables, aggregating or fixing
2462 * variables, changing the type of variables, modifying the graph that represents the instance of your application, and
2463 * the like.
2464 *
2465 * Typical methods called by a presolver are, for example, SCIPchgVarType(), SCIPfixVar(), SCIPaggregateVars(), SCIPtightenVarLb(),
2466 * and SCIPtightenVarUb().
2467 *
2468 *
2469 * @section PRESOL_ADDITIONALCALLBACKS Additional Callback Methods of a Presolver
2470 *
2471 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2472 * implemented for most applications, they can be used, for example, to initialize and free private data.
2473 * Additional callbacks can either be passed directly with SCIPincludePresol() to SCIP or via specific
2474 * <b>setter functions</b> after a call of SCIPincludePresolBasic(), see also @ref PRESOL_INTERFACE.
2475 *
2476 * @subsection PRESOLFREE
2477 *
2478 * 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.
2479 * This can be done by the following procedure:
2480 *
2481 * @refsnippet{src/scip/presol_boundshift.c,SnippetPresolFreeBoundshift}
2482 *
2483 * If you have allocated memory for fields in your presolver data, remember to free this memory
2484 * before freeing the presolver data itself.
2485 * If you are using the C++ wrapper class, this method is not available.
2486 * Instead, just use the destructor of your class to free the member variables of your class.
2487 *
2488 * @subsection PRESOLINIT
2489 *
2490 * The PRESOLINIT callback is executed after the problem is transformed.
2491 * The presolver may, e.g., use this call to initialize its presolver data.
2492 * The difference between the original and the transformed problem is explained in
2493 * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
2494 *
2495 * @subsection PRESOLCOPY
2496 *
2497 * The PRESOLCOPY callback is executed when a SCIP instance is copied, e.g. to
2498 * solve a sub-SCIP. By
2499 * defining this callback as
2500 * <code>NULL</code> the user disables the execution of the specified
2501 * presolver for all copied SCIP instances. This may deteriorate the performance
2502 * of primal heuristics using sub-SCIPs.
2503 *
2504 * @subsection PRESOLEXIT
2505 *
2506 * The PRESOLEXIT callback is executed before the transformed problem is freed.
2507 * In this method, the presolver should free all resources that have been allocated for the solving process in PRESOLINIT.
2508 *
2509 * @subsection PRESOLINITPRE
2510 *
2511 * The PRESOLINITPRE callback is executed when the presolving is about to begin.
2512 * The presolver may use this call to initialize its presolving data which only need to exist during the presolving stage.
2513 *
2514 * @subsection PRESOLEXITPRE
2515 *
2516 * The PRESOLEXITPRE callback is executed after presolving finishes and before the branch-and-bound process begins.
2517 * The presolver should use this call to clean up its presolving data, which was allocated in PRESOLINITPRE.
2518 */
2519
2520/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2521
2522/**@page SEPA How to add separators
2523 *
2524 * Separators are used to generate cutting planes that strengthen the LP relaxation of the problem formulation, but are
2525 * not required for a completeness and correctness of the model.
2526 * In contrast, constraint-based cutting planes, the second type of cutting planes in SCIP, are separated in the CONSSEPALP and
2527 * CONSSEPASOL callback methods of the constraint handlers, see \ref CONSSEPALP and \ref CONSSEPASOL. These cuts are
2528 * valid inequalities or even facets of the polyhedron described by a single constraint or a subset of the constraints of
2529 * a single constraint class. See also
2530 * "When should I implement a constraint handler, when should I implement a separator?" on \ref FAQ.
2531 * \n
2532 * A complete list of all separators contained in this release can be found \ref SEPARATORS "here".
2533 *
2534 * We now explain how users can add their own separators.
2535 * Take the separator for the class of Gomory mixed integer inequalities (src/scip/sepa_gomory.c) as an example.
2536 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjSepa wrapper
2537 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_SEPA... callback methods.
2538 *
2539 * Additional documentation for the callback methods of a separator, in particular for the input parameters,
2540 * can be found in the file type_sepa.h.
2541 *
2542 * Here is what you have to do to implement a separator:
2543 * -# Copy the template files src/scip/sepa_xyz.c and src/scip/sepa_xyz.h into files "sepa_myseparator.c"
2544 * and "sepa_myseparator.h".
2545 \n
2546 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2547 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2548 * -# Use `SCIPincludeSepaMyseparator()` in order to include the separator into your SCIP instance,
2549 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2550 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2551 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myseparator".
2552 * -# Adjust the properties of the separator (see \ref SEPA_PROPERTIES).
2553 * -# Define the separator data (see \ref SEPA_DATA). This is optional.
2554 * -# Implement the interface methods (see \ref SEPA_INTERFACE).
2555 * -# Implement the fundamental callback methods (see \ref SEPA_FUNDAMENTALCALLBACKS).
2556 * -# Implement the additional callback methods (see \ref SEPA_ADDITIONALCALLBACKS). This is optional.
2557 *
2558 *
2559 * @section SEPA_PROPERTIES Properties of a Separator
2560 *
2561 * At the top of the new file "sepa_myseparator.c", you can find the separator properties.
2562 * These are given as compiler defines.
2563 * In the C++ wrapper class, you have to provide the separator properties by calling the constructor
2564 * of the abstract base class scip::ObjSepa from within your constructor.
2565 * The properties you have to set have the following meaning:
2566 *
2567 * \par SEPA_NAME: the name of the separator.
2568 * This name is used in the interactive shell to address the separator.
2569 * Additionally, if you are searching for a separator with SCIPfindSepa(), this name is looked up.
2570 * Names have to be unique: no two separators may have the same name.
2571 *
2572 * \par SEPA_DESC: the description of the separator.
2573 * This string is printed as a description of the separator in the interactive shell.
2574 *
2575 * \par SEPA_PRIORITY: the priority of the separator.
2576 * In each separation round during the price-and-cut loop of the subproblem processing or the separation loop
2577 * of the primal solution separation, the separators and separation methods of the constraint handlers are called in
2578 * a predefined order, which is given by the priorities of the separators and the separation priorities
2579 * of the constraint handlers (see \ref CONS_PROPERTIES).
2580 * First, the separators with non-negative priority are called in the order of decreasing priority.
2581 * Next, the separation methods of the constraint handlers are called in the order of decreasing separation
2582 * priority.
2583 * Finally, the separators with negative priority are called in the order of decreasing priority. An easy way to list the
2584 * priorities of all separators and constraint handlers is to type "display separators" and "display conshdlrs" in
2585 * the interactive shell.
2586 * \n
2587 * The priority of the separator should be set according to the complexity of the cut separation algorithm and the
2588 * impact of the resulting cuts: separators that provide fast algorithms that usually have a high impact (i.e., cut off
2589 * a large portion of the LP relaxation) should have a high priority.
2590 * See \ref SEPAEXECLP and \ref SEPAEXECSOL for further details of the separation callbacks.
2591 *
2592 * \par SEPA_FREQ: the default frequency for separating cuts.
2593 * The frequency defines the depth levels at which the separation methods \ref SEPAEXECLP and \ref SEPAEXECSOL are called.
2594 * For example, a frequency of 7 means, that the separation callback is executed for subproblems that are in depth
2595 * 0, 7, 14, ... of the branching tree. A frequency of 0 means, that the separation method is only called at the root node.
2596 * A frequency of -1 disables the separator.
2597 * \n
2598 * The frequency can be adjusted by the user. This property of the separator only defines the default value of the frequency.
2599 * If you want to have a more flexible control of when to execute the separation algorithm, you have to assign
2600 * a frequency of 1 and implement a check at the beginning of your separation methods whether you really want to execute
2601 * the separation or not. If you do not want to execute it, set the result code of
2602 * \ref SEPAEXECLP and \ref SEPAEXECSOL to SCIP_DIDNOTRUN.
2603 *
2604 * \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.
2605 * At the current branch-and-bound node, the relative distance from its dual bound (local dual bound)
2606 * to the primal bound compared to the best node's dual bound (global dual bound) is considered. The separation method
2607 * of the separator will only be applied at the current node if this relative distance does not exceed SEPA_MAXBOUNDDIST.
2608 * \n
2609 * For example, if the global dual bound is 50 and the primal bound is 60, SEPA_MAXBOUNDDIST = 0.25 means that separation
2610 * 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
2611 * than or equal to 52.5.
2612 * \n
2613 * In particular, the values 0.0 and 1.0 mean that separation is applied at the current best node only or at all
2614 * nodes, respectively. Since separation seems to be most important to apply at nodes that define to the global
2615 * dual bound, 0.0 is probably a good choice for SEPA_MAXBOUNDDIST.
2616 * Note that separators with a frequency of SEPA_FREQ = 0 are only applied at the root node.
2617 * Obviously, at the root node the local dual bound is equal to the global dual bound and thus, the separator is called
2618 * for any value of SEPA_MAXBOUNDDIST.
2619 *
2620 * \par SEPA_USESSUBSCIP: Does the separator use a secondary SCIP instance?
2621 * Some heuristics and separators solve MIPs or SAT problems and use a secondary SCIP instance. Examples are
2622 * Large Neighborhood Search heuristics such as RINS and Local Branching or the CGMIP separator. To avoid recursion,
2623 * these plugins usually deactivate all other plugins that solve MIPs. If a separator uses a secondary SCIP instance,
2624 * this parameter has to be TRUE and it is recommended to call SCIPsetSubscipsOff() for the secondary SCIP instance.
2625 *
2626 * \par SEPA_DELAY: the default for whether the separation method should be delayed, if other separators or constraint handlers found cuts.
2627 * If the separator's separation method is marked to be delayed, it is only executed after no other separator
2628 * or constraint handler found a cut during the price-and-cut loop.
2629 * If the separation method of the separator is very expensive, you may want to mark it to be delayed until all cheap
2630 * separation methods have been executed.
2631 *
2632 * @section SEPA_DATA Separator Data
2633 *
2634 * Below the header "Data structures" you can find a struct which is called "struct SCIP_SepaData".
2635 * In this data structure, you can store the data of your separator. For example, you should store the adjustable
2636 * parameters of the separator in this data structure. In a separator, user parameters for the maximal number of
2637 * separation rounds per node and for the maximal number of cuts separated per separation round might be useful.
2638 * If you are using C++, you can add separator data as usual as object variables to your class.
2639 * \n
2640 * Defining separator data is optional. You can leave the struct empty.
2641 *
2642 * @section SEPA_INTERFACE Interface Methods
2643 *
2644 * At the bottom of "sepa_myseparator.c", you can find the interface method SCIPincludeSepaMyseparator(),
2645 * which also appears in "sepa_myseparator.h"
2646 * SCIPincludeSepaMyseparator() is called by the user, if (s)he wants to include the separator,
2647 * i.e., if (s)he wants to use the separator in his/her application.
2648 *
2649 * This method only has to be adjusted slightly.
2650 * It is responsible for notifying SCIP of the presence of the separator. For this, you can either call SCIPincludeSepa(),
2651 * or SCIPincludeSepaBasic() since SCIP version 3.0. In the latter variant, \ref SEPA_ADDITIONALCALLBACKS "additional callbacks"
2652 * must be added via setter functions as, e.g., SCIPsetSepaCopy(). We recommend this latter variant because
2653 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2654 * variant must be manually adjusted with every SCIP release containing new callbacks for separators in order to compile.
2655 *
2656 * If you are using separator data, you have to allocate the memory
2657 * for the data at this point. You can do this by calling:
2658 * \code
2659 * SCIP_CALL( SCIPallocBlockMemory(scip, &sepadata) );
2660 * \endcode
2661 * You also have to initialize the fields in "struct SCIP_SepaData" afterwards. For freeing the
2662 * separator data, see \ref SEPAFREE.
2663 *
2664 * You may also add user parameters for your separator, see \ref PARAM for how to add user parameters and
2665 * the method SCIPincludeSepaGomory() in src/scip/sepa_gomory.c for an example.
2666 *
2667 *
2668 * @section SEPA_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Separator
2669 *
2670 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2671 * an operational algorithm.
2672 * They are passed together with the separator itself to SCIP using SCIPincludeSepa() or SCIPincludeSepaBasic(),
2673 * see @ref SEPA_INTERFACE.
2674 *
2675 * Separator plugins have two callbacks, @ref SEPAEXECLP and @ref SEPAEXECSOL, of which at least one must be implemented.
2676 *
2677 * Additional documentation for the callback methods, in particular to their input parameters,
2678 * can be found in type_sepa.h.
2679 *
2680 * @subsection SEPAEXECLP
2681 *
2682 * The SEPAEXECLP callback is executed during the price-and-cut loop of the subproblem processing.
2683 * It should try to generate general purpose cutting planes in order to separate the current LP solution.
2684 * The method is called in the LP solution loop, which means that a valid LP solution exists.
2685 *
2686 * Usually, the callback searches and produces cuts, that are added with a call to SCIPaddCut().
2687 * If the cut should be added to the global cut pool, it calls SCIPaddPoolCut().
2688 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
2689 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
2690 * In addition to LP rows, the callback may also produce domain reductions or add additional constraints.
2691 *
2692 * Overall, the SEPAEXECLP callback has the following options, which is indicated by the possible return values of
2693 * the 'result' variable (see type_sepa.h):
2694 * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
2695 * - adding an additional constraint (result SCIP_CONSADDED)
2696 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
2697 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
2698 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
2699 * (result SCIP_DIDNOTFIND)
2700 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
2701 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
2702 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
2703 *
2704 * @subsection SEPAEXECSOL
2705 *
2706 * The SEPAEXECSOL callback is executed during the separation loop on arbitrary primal solutions.
2707 * It should try to generate general purpose cutting planes in order to separate the given primal solution.
2708 * The method is not called in the LP solution loop, which means that there is no valid LP solution.
2709 *
2710 * In the standard SCIP environment, the SEPAEXECSOL callback is not used because only LP solutions are
2711 * separated. The SEPAEXECSOL callback provides means to support external relaxation handlers like semidefinite
2712 * relaxations that want to separate an intermediate primal solution vector. Thus, if you do not want to support
2713 * such external plugins, you do not need to implement this callback method.
2714 *
2715 * Usually, the callback searches and produces cuts, that are added with a call to SCIPaddCut().
2716 * If the cut should be added to the global cut pool, it calls SCIPaddPoolCut().
2717 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
2718 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
2719 * In addition to LP rows, the callback may also produce domain reductions or add other constraints.
2720 *
2721 * Overall, the SEPAEXECSOL callback has the following options, which is indicated by the possible return values of
2722 * the 'result' variable (see type_sepa.h):
2723 * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
2724 * - adding an additional constraint (result SCIP_CONSADDED)
2725 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
2726 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
2727 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
2728 * (result SCIP_DIDNOTFIND)
2729 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
2730 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
2731 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
2732 *
2733 *
2734 * @section SEPA_ADDITIONALCALLBACKS Additional Callback Methods of a Separator
2735 *
2736 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2737 * implemented for most applications, they can be used, for example, to initialize and free private data.
2738 * Additional callbacks can either be passed directly with SCIPincludeSepa() to SCIP or via specific
2739 * <b>setter functions</b> after a call of SCIPincludeSepaBasic(), see also @ref SEPA_INTERFACE.
2740 *
2741 * @subsection SEPAFREE
2742 *
2743 * If you are using separator data (see \ref SEPA_DATA and \ref SEPA_INTERFACE), you have to implement this method
2744 * in order to free the separator data. This can be done by the following procedure:
2745 *
2746 * @refsnippet{src/scip/sepa_gomory.c,SnippetSepaFreeGomory}
2747 *
2748 * If you have allocated memory for fields in your separator data, remember to free this memory
2749 * before freeing the separator data itself.
2750 * If you are using the C++ wrapper class, this method is not available.
2751 * Instead, just use the destructor of your class to free the member variables of your class.
2752 *
2753 * @subsection SEPACOPY
2754 *
2755 * The SEPACOPY callback is executed when a SCIP instance is copied, e.g. to
2756 * solve a sub-SCIP. By
2757 * defining this callback as
2758 * <code>NULL</code> the user disables the execution of the specified
2759 * separator for all copied SCIP instances. This may deteriorate the performance
2760 * of primal heuristics using sub-SCIPs.
2761 *
2762 * @subsection SEPAINIT
2763 *
2764 * The SEPAINIT callback is executed after the problem is transformed.
2765 * The separator may, e.g., use this call to initialize its separator data.
2766 * The difference between the original and the transformed problem is explained in
2767 * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
2768 *
2769 * @subsection SEPAEXIT
2770 *
2771 * The SEPAEXIT callback is executed before the transformed problem is freed.
2772 * In this method, the separator should free all resources that have been allocated for the solving process in SEPAINIT.
2773 *
2774 * @subsection SEPAINITSOL
2775 *
2776 * The SEPAINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
2777 * begin. The separator may use this call to initialize its branch-and-bound specific data.
2778 *
2779 * @subsection SEPAEXITSOL
2780 *
2781 * The SEPAEXITSOL callback is executed before the branch-and-bound process is freed. The separator should use this call
2782 * to clean up its branch-and-bound data, in particular to release all LP rows that it has created or captured.
2783 */
2784
2785/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2786
2787/**@page PROP How to add propagators
2788 *
2789 * Propagators are used to tighten the domains of the variables. Like for cutting planes, there are two different types
2790 * of domain propagations. Constraint based (primal) domain propagation algorithms are part of the corresponding
2791 * constraint handlers, see \ref CONSPROP. In contrast, domain propagators usually provide dual propagations, i.e.,
2792 * propagations that can be applied using the objective function and the current best known primal solution. This
2793 * section deals with such propagators.
2794 *
2795 * A complete list of all propagators contained in this release can be found \ref PROPAGATORS "here".
2796 *
2797 * We now explain how users can add their own propagators. Take the pseudo objective function propagator
2798 * (src/scip/prop_pseudoobj.c) as an example. As all other default plugins, it is written in C. C++ users can easily
2799 * adapt the code by using the scip::ObjProp wrapper base class and implement the @c scip_...() virtual methods instead
2800 * of the @c SCIP_DECL_PROP... callback methods.
2801 *
2802 * Additional documentation for the callback methods of a propagator can be found in the file type_prop.h.
2803 *
2804 * Here is what you have to do to implement a propagator:
2805 * -# Copy the template files src/scip/prop_xyz.c and src/scip/prop_xyz.h into files named "prop_mypropagator.c"
2806 * and "prop_mypropagator.h".
2807 * \n
2808 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2809 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2810 * -# Use `SCIPincludePropMypropagator()` in order to include the propagator into your SCIP instance,
2811 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2812 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2813 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypropagator".
2814 * -# Adjust the properties of the propagator (see \ref PROP_PROPERTIES).
2815 * -# Define the propagator data (see \ref PROP_DATA). This is optional.
2816 * -# Implement the interface methods (see \ref PROP_INTERFACE).
2817 * -# Implement the fundamental callback methods (see \ref PROP_FUNDAMENTALCALLBACKS).
2818 * -# Implement the additional callback methods (see \ref PROP_ADDITIONALCALLBACKS). This is optional.
2819 *
2820 * @section PROP_PROPERTIES Properties of a Propagator
2821 *
2822 * At the top of the new file "prop_mypropagator.c" you can find the propagator properties. These are given as compiler
2823 * defines. The presolving-related properties are optional,
2824 * they only have to be defined if the propagator supports presolving routines.
2825 * In the C++ wrapper class, you have to provide the propagator properties by calling the constructor of the
2826 * abstract base class scip::ObjProp from within your constructor. The properties you have the following meaning:
2827 *
2828 * @subsection PROP_FUNDAMENTALPROPERTIES Fundamental properties of a propagator
2829 *
2830 * \par PROP_NAME: the name of the propagator.
2831 * This name is used in the interactive shell to address the propagator. Additionally, if you are searching for a
2832 * propagator with SCIPfindProp(), this name is searched for. Names have to be unique: no two propagators may have the
2833 * same name.
2834 *
2835 * \par PROP_DESC: the description of the propagator.
2836 * This string is printed as a description of the propagator in the interactive shell.
2837 *
2838 * \par PROP_PRIORITY: the priority of the propagator.
2839 * In each propagation round, the propagators and propagation methods of the constraint handlers are called in a
2840 * predefined order, which is given by the priorities of the propagators and the check priorities of the constraint
2841 * handlers. First, the propagators with non-negative priority are called in order of decreasing priority. Next, the
2842 * propagation methods of the different constraint handlers are called in order of decreasing check priority. Finally,
2843 * the propagators with negative priority are called in order of decreasing priority. \n The priority of the
2844 * propagators should be set according to the complexity of the propagation algorithm and the impact of the domain
2845 * propagations: propagators providing fast algorithms that usually have a high impact (i.e., tighten many bounds)
2846 * should have a high priority.
2847 *
2848 * \par PROP_FREQ: the default frequency for propagating domains.
2849 * The frequency defines the depth levels at which the propagation method \ref PROPEXEC is called. For example, a
2850 * frequency of 7 means, that the propagation callback is executed for subproblems that are in depth 0, 7, 14, ... of
2851 * the branching tree. A frequency of 0 means that propagation is only applied in preprocessing and at the root node. A
2852 * frequency of -1 disables the propagator.
2853 * \n
2854 * The frequency can be adjusted by the user. This property of the propagator only defines the default value of the
2855 * frequency.\n
2856 * <b>Note:</b> If you want to have a more flexible control of when to execute the propagation algorithm, you have to
2857 * assign a frequency of 1 and implement a check at the beginning of your propagation algorithm whether you really want
2858 * to execute the domain propagation or not. If you do not want to execute it, set the result code to SCIP_DIDNOTRUN.
2859 *
2860 * \par PROP_DELAY: the default for whether the propagation method should be delayed, if other propagators or constraint handlers found domain reductions.
2861 * If the propagator's propagation method is marked to be delayed, it is only executed after no other propagator or
2862 * constraint handler found a domain reduction in the current iteration of the domain propagation loop. If the
2863 * propagation method of the propagator is very expensive, you may want to mark it to be delayed until all cheap
2864 * propagation methods have been executed.
2865 *
2866 * \par PROP_TIMING: the timing mask of the propagator.
2867 * SCIP calls the domain propagation routines at different places in the node processing loop.
2868 * This property indicates at which places the propagator is called.
2869 * Possible values are defined in type_timing.h and can be concatenated, e.g., as in SCIP_PROPTIMING_ALWAYS.
2870 *
2871 * @subsection PROP_ADDITIONALPROPERTIES Optional propagator properties
2872 *
2873 * The following properties are optional and only need to be defined if the propagator supports
2874 * presolving, that is, if the \ref PROPPRESOL "presolving callback" is implemented.
2875
2876 * \par PROP_PRESOLTIMING: the timing of the presolving method (FAST, MEDIUM, or EXHAUSTIVE).
2877 * Every presolving round starts with the FAST presolving methods. MEDIUM presolvers are only called, if FAST presolvers did not find
2878 * enough reductions in this round so far, and EXHAUSTIVE presolving steps are only performed if all presolvers called before
2879 * in this round were unsuccessful.
2880 * Presolving methods should be assigned a timing based on how expensive they are, e.g., presolvers that provide fast algorithms that
2881 * usually have a high impact (i.e., remove lots of variables or tighten bounds of many variables) should have a timing FAST.
2882 * If a presolving method implements different algorithms of different complexity, it may also get multiple timings and check the timing
2883 * internally in the \ref PROPPRESOL callback to decide which algorithms to run.
2884 *
2885 * \par PROP_PRESOL_PRIORITY: the priority of the presolving method.
2886 * This attribute is analogous to the PROP_PRIORITY flag, but deals with the preprocessing method of the presolver.
2887 *
2888 * \par PROP_PRESOL_MAXROUNDS: the default maximal number of presolving rounds the propagator participates in.
2889 * The preprocessing is executed in rounds.
2890 * If enough changes have been applied to the model, an additional preprocessing round is performed.
2891 * The MAXROUNDS parameter of a propagator denotes the maximal number of preprocessing rounds, the propagator
2892 * participates in.
2893 * A value of -1 means, that there is no limit on the number of rounds.
2894 * A value of 0 means, the preprocessing callback of the propagator is disabled.
2895 *
2896 * @section PROP_DATA Propagator Data
2897 *
2898 * Below the title "Data structures" you can find a struct called <code>struct SCIP_PropData</code>. In this data
2899 * structure, you can store the data of your propagator. For example, you should store the adjustable parameters of the
2900 * propagator in this data structure. If you are using C++, you can add propagator data as object variables to your
2901 * class as usual .
2902 * \n
2903 * Defining propagator data is optional. You can leave the struct empty.
2904 *
2905 *
2906 * @section PROP_INTERFACE Interface Methods
2907 *
2908 * At the bottom of "prop_mypropagator.c", you can find the interface method SCIPincludeSepaMypropagator(),
2909 * which also appears in "prop_mypropagator.h"
2910 * SCIPincludePropMypropagator() is called by the user, if (s)he wants to include the propagator,
2911 * i.e., if (s)he wants to use the propagator in his/her application.
2912 *
2913 * This method only has to be adjusted slightly.
2914 * It is responsible for notifying SCIP of the presence of the propagator. For this, you can either call SCIPincludeProp(),
2915 * or SCIPincludePropBasic() since SCIP version 3.0. In the latter variant, \ref PROP_ADDITIONALCALLBACKS "additional callbacks"
2916 * must be added via setter functions as, e.g., SCIPsetPropCopy(). We recommend this latter variant because
2917 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2918 * variant must be manually adjusted with every SCIP release containing new callbacks for separators in order to compile.
2919 *
2920 *
2921 * If you are using propagator data, you have to allocate the memory for the data at this point. You can do this by
2922 * calling
2923 * \code
2924 * SCIP_CALL( SCIPallocBlockMemory(scip, &propdata) );
2925 * \endcode
2926 * You also have to initialize the fields in <code>struct SCIP_PropData</code> afterwards.
2927 *
2928 * You may also add user parameters for your propagator, see the method SCIPincludePropPseudoobj() in
2929 * src/scip/prop_pseudoobj.c for an example.
2930 *
2931 *
2932 * @section PROP_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Propagator
2933 *
2934 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2935 * an operational algorithm.
2936 * They are passed together with the propagator itself to SCIP using SCIPincludeProp() or SCIPincludePropBasic(),
2937 * see @ref PROP_INTERFACE.
2938 *
2939 * Propagator plugins have one fundamental callback method, namely the \ref PROPEXEC method
2940 * method. This method has to be implemented for every propagator; the other callback methods are optional. In the
2941 * C++ wrapper class scip::ObjProp, the scip_exec() method (which corresponds to the \ref PROPEXEC
2942 * callback) is a virtual abstract member function. You have to
2943 * implement it in order to be able to construct an object of your propagator class.
2944 *
2945 * Additional documentation for the callback methods can be found in type_prop.h.
2946 *
2947 * @subsection PROPEXEC
2948 *
2949 * The PROPEXEC callback is called during presolving and during the subproblem processing. It should perform the actual
2950 * domain propagation, which means that it should tighten the variables' bounds. The technique of domain propagation,
2951 * which is the main workhorse of constraint programming, is called "node preprocessing" in the Integer Programming
2952 * community.
2953 *
2954 * The PROPEXEC callback has the following options:
2955 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
2956 * - reducing (i.e, tightening) the domains of some variables (result SCIP_REDUCEDDOM)
2957 * - stating that the propagator searched, but did not find domain reductions, cutting planes, or cut constraints
2958 * (result SCIP_DIDNOTFIND)
2959 * - stating that the propagator was skipped (result SCIP_DIDNOTRUN)
2960 * - stating that the propagator was skipped, but should be called again (result SCIP_DELAYED)
2961 *
2962 *
2963 *
2964 * @section PROP_ADDITIONALCALLBACKS Additional Callback Methods of a Propagator
2965 *
2966 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2967 * implemented for most applications, they can be used, for example, to initialize and free private data.
2968 * Additional callbacks can either be passed directly with SCIPincludeProp() to SCIP or via specific
2969 * <b>setter functions</b> after a call of SCIPincludePropBasic(), see also @ref PROP_INTERFACE.
2970 *
2971 * @subsection PROPRESPROP
2972 *
2973 * If the propagator wants to support \ref CONF "conflict analysis", it has to supply the PROPRESPROP method. It also should call
2974 * SCIPinferVarLbProp() or SCIPinferVarUbProp() in the domain propagation instead of SCIPchgVarLb() or SCIPchgVarUb() in
2975 * order to deduce bound changes on variables. In the SCIPinferVarLbProp() and SCIPinferVarUbProp() calls, the
2976 * propagator provides a pointer to itself and an integer value "inferinfo" that can be arbitrarily chosen.
2977 *
2978 * The propagation conflict resolving method PROPRESPROP must then be implemented to provide the "reasons" for the bound
2979 * changes, i.e., the bounds of variables at the time of the propagation, which forced the propagator to set the
2980 * conflict variable's bound to its current value. It can use the "inferinfo" tag to identify its own propagation rule
2981 * and thus identify the "reason" bounds. The bounds that form the reason of the assignment must then be provided by
2982 * calls to SCIPaddConflictLb() and SCIPaddConflictUb() in the propagation conflict resolving method.
2983 *
2984 * See the description of the propagation conflict resolving method \ref CONSRESPROP of constraint handlers for
2985 * further details.
2986 *
2987 * Omitting the PROPRESPROP callback circumvents the implementation of the usually rather complex conflict resolving method.
2988 * Yet, it
2989 * will make the conflict analysis less effective. We suggest to first omit the conflict resolving method and check how
2990 * effective the propagation method is. If it produces a lot of propagations for your application, you definitely should
2991 * consider implementing the conflict resolving method.
2992 *
2993 *
2994 * @subsection PROPFREE
2995 *
2996 * If you are using propagator data, you have to implement this method in order to free the propagator data.
2997 * This can be done by the following procedure:
2998 *
2999 * @refsnippet{src/scip/prop_redcost.c,SnippetPropFreeRedcost}
3000 *
3001 * If you have allocated memory for fields in your propagator data, remember to free this memory
3002 * before freeing the propagator data itself.
3003 * If you are using the C++ wrapper class, this method is not available.
3004 * Instead, just use the destructor of your class to free the member variables of your class.
3005 *
3006 * @subsection PROPINIT
3007 *
3008 * The PROPINIT callback is executed after the problem is transformed. The propagator may, e.g., use this call to
3009 * initialize its propagator data.
3010 *
3011 * @subsection PROPCOPY
3012 *
3013 * The PROPCOPY callback is executed when a SCIP instance is copied, e.g. to
3014 * solve a sub-SCIP. By
3015 * defining this callback as
3016 * <code>NULL</code> the user disables the execution of the specified
3017 * propagator for all copied SCIP instances. This may deteriorate the performance
3018 * of primal heuristics using sub-SCIPs.
3019 *
3020 * @subsection PROPEXIT
3021 *
3022 * The PROPEXIT callback is executed before the transformed problem is freed.
3023 * In this method, the propagator should free all resources that have been allocated for the solving process in PROPINIT.
3024 *
3025 * @subsection PROPINITPRE
3026 *
3027 * The PROPINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
3028 * The propagator may use this call to initialize its presolving data before the presolving process begins.
3029 *
3030 * @subsection PROPEXITPRE
3031 *
3032 * The PROPEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
3033 * The propagator may use this call, e.g., to clean up its presolving data.
3034 * Besides clean up, no time consuming operations should be done.
3035 *
3036 * @subsection PROPINITSOL
3037 *
3038 * The PROPINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3039 * begin.
3040 * The propagator may use this call to initialize its branch-and-bound specific data.
3041 *
3042 * @subsection PROPEXITSOL
3043 *
3044 * The PROPEXITSOL callback is executed before the branch-and-bound process is freed.
3045 * The propagator should use this call to clean up its branch-and-bound data.
3046 *
3047 * @subsection PROPPRESOL
3048 *
3049 * Seaches for domain propagations, analogous to the \ref PROPEXEC callback.
3050 * However, this callback is called during preprocessing.
3051 *
3052 * To inform SCIP that the presolving method found a reduction the result pointer has to be set in a proper way.
3053 * The following options are possible:
3054 *
3055 * - SCIP_UNBOUNDED : at least one variable is not bounded by any constraint in objective direction
3056 * - SCIP_CUTOFF : at least one domain reduction that renders the problem infeasible has been found
3057 * - SCIP_SUCCESS : the presolver found a domain reduction
3058 * - SCIP_DIDNOTFIND : the presolver searched, but did not find a presolving change
3059 * - SCIP_DIDNOTRUN : the presolver was skipped
3060 * - SCIP_DELAYED : the presolver was skipped, but should be called again
3061 *
3062 *
3063 * Please see also the @ref PROP_ADDITIONALPROPERTIES section to learn about the properties
3064 * PROP_PRESOLTIMING and PROP_PRESOL_MAXROUNDS, which influence the behaviour of SCIP
3065 * calling PROPPRESOL.
3066 *
3067 */
3068
3069/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3070
3071/**@page BRANCH How to add branching rules
3072 *
3073 * Branching rules are used to split the problem at the current node into smaller subproblems. Branching rules can be called at three
3074 * different occasions, which is why they have three different execution methods (see \ref
3075 * BRANCHRULE_ADDITIONALCALLBACKS). Branching is performed if:
3076 * - the LP solution of the current problem is fractional. In this case, the integrality constraint handler calls the
3077 * \ref BRANCHEXECLP methods of the branching rules.
3078 * - the list of external branching candidates is not empty. This will only be the case if branching candidates were added
3079 * by a user's \ref RELAX "relaxation handler" or \ref CONS "constraint handler" plugin, calling SCIPaddExternBranchCand().
3080 * These branching candidates should be processed by the \ref BRANCHEXECEXT method.
3081 * - if an integral solution violates one or more constraints and this infeasibility could not be resolved in the callback methods
3082 * \ref CONSENFOLP and \ref CONSENFOPS of the corresponding constraint handlers. In this case, the \ref BRANCHEXECPS method will be called. This is the
3083 * 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
3084 * branching on pseudo solutions works as a last resort.
3085 *
3086 * The idea of branching rules is to take a global view on the problem. In contrast, branching paradigms which are
3087 * specific to one type of constraint are best implemented within the enforcement callbacks of your constraint handler.
3088 * See, e.g., the constraint specific branching rules provided by the constraint handlers for special ordered sets
3089 * (src/scip/cons_sos{1,2}.c)).
3090 * \n
3091 * All branching rules that come with the default distribution of SCIP create two subproblems by splitting a single
3092 * variable's domain. It is, however, fully supported to implement much more general branching schemes, for example by
3093 * creating more than two subproblems, or by adding additional constraints to the subproblems instead of tightening the
3094 * domains of the variables.
3095 * \n
3096 * A complete list of all branching rules contained in this release can be found \ref BRANCHINGRULES "here".
3097 *
3098 * We now explain how users can add their own branching rules. Take the most infeasible LP branching rule
3099 * (src/scip/branch_mostinf.c) as an example. As all other default plugins, it is written in C. C++ users can easily
3100 * adapt the code by using the scip::ObjBranchrule wrapper base class and implement the scip_...() virtual methods instead of
3101 * the SCIP_DECL_BRANCH... callback methods.
3102 *
3103 * Additional documentation for the callback methods of a branching rule can be found in the file type_branch.h.
3104 *
3105 * Here is what you have to do to implement a branching rule:
3106 * -# Copy the template files src/scip/branch_xyz.c and src/scip/branch_xyz.h into files named
3107 * "branch_mybranchingrule.c" and "branch_mybranchingrule.h".
3108 * \n
3109 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
3110 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
3111 * -# Use `SCIPincludeBranchruleMybranchingrule()` in order to include the branching rule into your SCIP instance,
3112 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
3113 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
3114 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mybranchingrule".
3115 * -# Adjust the properties of the branching rule (see \ref BRANCHRULE_PROPERTIES).
3116 * -# Define the branching rule data (see \ref BRANCHRULE_DATA). This is optional.
3117 * -# Implement the interface methods (see \ref BRANCHRULE_INTERFACE).
3118 * -# Implement the fundamental callback methods (see \ref BRANCHRULE_FUNDAMENTALCALLBACKS).
3119 * -# Implement the additional callback methods (see \ref BRANCHRULE_ADDITIONALCALLBACKS). This is optional.
3120 *
3121 *
3122 * @section BRANCHRULE_PROPERTIES Properties of a Branching Rule
3123 *
3124 * At the top of the new file "branch_mybranchingrule.c" you can find the branching rule properties.
3125 * These are given as compiler defines.
3126 * In the C++ wrapper class, you have to provide the branching rule properties by calling the constructor
3127 * of the abstract base class scip::ObjBranchrule from within your constructor.
3128 * The properties you have to set have the following meaning:
3129 *
3130 * \par BRANCHRULE_NAME: the name of the branching rule.
3131 * This name is used in the interactive shell to address the branching rule.
3132 * Additionally, if you are searching for a branching rule with SCIPfindBranchrule(), this name is looked up.
3133 * Names have to be unique: no two branching rules may have the same name.
3134 *
3135 * \par BRANCHRULE_DESC: the description of the branching rule.
3136 * This string is printed as a description of the branching rule in the interactive shell.
3137 *
3138 * \par BRANCHRULE_PRIORITY: the default value for the priority of the branching rule.
3139 * In the subproblem processing, the branching rules are called in decreasing order of their priority until
3140 * one succeeded to branch. Since most branching rules are able to generate a branching in all situations,
3141 * only the rule of highest priority is used. In combination with the BRANCHRULE_MAXDEPTH and
3142 * BRANCHRULE_MAXBOUNDDIST settings, however, interesting strategies can be easily employed. For example,
3143 * the user can set the priority of the "full strong branching" strategy to the highest value and assign the
3144 * second highest value to the "reliable pseudo cost" rule. If (s)he also sets the maximal depth for the
3145 * "full strong branching" to 5, in the top 5 depth levels of the search tree the "full strong branching" is
3146 * applied, while in the deeper levels "reliable pseudo cost branching" is used.
3147 * \n
3148 * Note that the BRANCHRULE_PRIORITY property only specifies the default value of the priority. The user can
3149 * change this value arbitrarily.
3150 *
3151 * \par BRANCHRULE_MAXDEPTH: the default value for the maximal depth level of the branching rule.
3152 * This parameter denotes the maximal depth level in the branch-and-bound tree up to which the branching method of the
3153 * branching rule will be applied. Use -1 for no limit.
3154 * \n
3155 * Note that this property only specifies the default value. The user can change this value arbitrarily.
3156 *
3157 * \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.
3158 * At the current branch-and-bound node, the relative distance from its dual bound (local dual bound)
3159 * to the primal bound compared to the best node's dual bound (global dual bound) is considered. The branching method of
3160 * the branching rule will only be applied at the node if this relative distance does not exceed BRANCHRULE_MAXBOUNDDIST.
3161 * \n
3162 * For example, if the global dual bound is 50 and the primal bound is 60, BRANCHRULE_MAXBOUNDDIST = 0.25 means that
3163 * 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
3164 * 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
3165 * current best node only or at all nodes, respectively.
3166 * \n
3167 * Note that the BRANCHRULE_MAXBOUNDDIST property only specifies the default value of the maximal bound distance.
3168 * The user can change this value arbitrarily.
3169 *
3170 *
3171 * @section BRANCHRULE_DATA Branching Rule Data
3172 *
3173 * Below the header "Data structures" you can find a struct which is called "struct SCIP_BranchruleData".
3174 * In this data structure, you can store the data of your branching rule. For example, you should store the adjustable
3175 * parameters of the branching rule in this data structure.
3176 * If you are using C++, you can add branching rule data as usual as object variables to your class.
3177 * \n
3178 * Defining branching rule data is optional. You can leave the struct empty.
3179 *
3180 *
3181 * @section BRANCHRULE_INTERFACE Interface Methods
3182 *
3183 * At the bottom of "branch_mybranchingrule.c", you can find the interface method SCIPincludeBranchruleMybranchingrule(),
3184 * which also appears in "branch_mybranchingrule.h"
3185 * SCIPincludeBranchruleMybranchingrule() is called by the user, if (s)he wants to include the branching rule,
3186 * i.e., if (s)he wants to use the branching rule in his/her application.
3187 *
3188 * This method only has to be adjusted slightly.
3189 * It is responsible for notifying SCIP of the presence of the branching rule. For this, you can either call
3190 * SCIPincludeBranchrule(),
3191 * or SCIPincludeBranchruleBasic() since SCIP version 3.0. In the latter variant, \ref BRANCHRULE_ADDITIONALCALLBACKS "additional callbacks"
3192 * must be added via setter functions as, e.g., SCIPsetBranchruleCopy(). We recommend this latter variant because
3193 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3194 * variant must be manually adjusted with every SCIP release containing new callbacks for branchrule in order to compile.
3195 *
3196 *
3197 * If you are using branching rule data, you have to allocate the memory for the data at this point.
3198 * You can do this by calling:
3199 * \code
3200 * SCIP_CALL( SCIPallocBlockMemory(scip, &branchruledata) );
3201 * \endcode
3202 * You also have to initialize the fields in struct SCIP_BranchruleData afterwards.
3203 *
3204 * You may also add user parameters for your branching rule, see the method SCIPincludeBranchruleRelpscost() in
3205 * src/scip/branch_relpscost.c for an example.
3206 *
3207 *
3208 * @section BRANCHRULE_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Branching Rule
3209 *
3210 * Branching rules do not have any fundamental callback methods, i.e., all callback methods are optional.
3211 * In most cases, however, you want to implement the \ref BRANCHEXECLP method and sometimes the \ref BRANCHEXECPS method.
3212 *
3213 *
3214 * @section BRANCHRULE_ADDITIONALCALLBACKS Additional Callback Methods of a Branching Rule
3215 *
3216 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
3217 * implemented for most applications, they can be used, for example, to initialize and free private data.
3218 * Additional callbacks can either be passed directly with SCIPincludeBranchrule() to SCIP or via specific
3219 * <b>setter functions</b> after a call of SCIPincludeBranchruleBasic(), see also @ref BRANCHRULE_INTERFACE.
3220 *
3221 * The most important callback methods are the \ref BRANCHEXECLP, \ref BRANCHEXECEXT,
3222 * and \ref BRANCHEXECPS methods, which perform the actual task of generating a branching.
3223 *
3224 * Additional documentation for the callback methods can be found in type_branch.h.
3225 *
3226 * @subsection BRANCHEXECLP
3227 *
3228 * The BRANCHEXECLP callback is executed during node processing if a fractional LP solution is available. It should
3229 * split the current problem into smaller subproblems. Usually, the branching is done in a way such that the current
3230 * fractional LP solution is no longer feasible in the relaxation of the subproblems. It is, however, possible to
3231 * create a child node for which the fractional LP solution is still feasible in the relaxation, for example, by
3232 * branching on a variable with integral LP value. In every case, you have to make sure that each subproblem is a
3233 * proper restriction of the current problem. Otherwise, you risk to produce an infinite path in the search tree.
3234 *
3235 * The user gains access to the branching candidates, i.e., to the fractional variables, and their LP solution values by
3236 * calling the method SCIPgetLPBranchCands(). Furthermore, SCIP provides two methods for performing the actual
3237 * branching, namely SCIPbranchVar() and SCIPcreateChild().
3238 *
3239 * Given an integral variable \f$x\f$ with fractional LP solution value \f$x^*\f$, the method SCIPbranchVar() creates
3240 * two child nodes; one contains the bound \f$x \le \lfloor x^* \rfloor\f$ and the other one contains the bound \f$x \ge
3241 * \lceil x^* \rceil\f$, see the BRANCHEXECLP callback in src/scip/branch_mostinf.c for an example. In addition, if a
3242 * proven lower objective bound of a created child node is known, like after strong branching has been applied, the user
3243 * may call the method SCIPupdateNodeLowerbound() in order to update the child node's lower bound.
3244 *
3245 * Please also see the \ref BRANCHEXEC "further information for the three execution methods".
3246 *
3247 * @subsection BRANCHEXECEXT
3248 *
3249 * The BRANCHEXECEXT callback is executed during node processing if no LP solution is available and the list of
3250 * external branching candidates is not empty. It should split the current problem into smaller subproblems. If you
3251 * do not use relaxation handlers or constraints handlers that provide external branching candidates, you do not need to
3252 * implement this callback.
3253 *
3254 * In contrast to the LP branching candidates and the pseudo branching candidates, the list of external branching
3255 * candidates will not be generated automatically. The user has to add all variables to the list by calling
3256 * SCIPaddExternBranchCand() for each of them. Usually, this will happen in the execution method of a relaxation handler or in the
3257 * enforcement methods of a constraint handler.
3258 *
3259 * The user gains access to these branching candidates by calling the method SCIPgetExternBranchCands(). Furthermore,
3260 * SCIP provides two methods for performing the actual branching with a given solution value, namely SCIPbranchVarVal()
3261 * and SCIPcreateChild(). SCIPbranchVarVal() allows users to specify the branching point for a variable in contrast to
3262 * SCIPbranchVar(), which will always use the current LP or pseudo solution.
3263 *
3264 * This paragraph contains additional information regarding how the method SCIPbranchVarVal() works. For external branching candidates,
3265 * there are three principle possibilities:
3266 * - Given a continuous variable \f$x\f$ with solution value \f$x^*\f$, the method SCIPbranchVarVal() creates
3267 * two child nodes; one contains the bound \f$x \le x^* \f$ and the other one contains the bound \f$x \ge x^* \f$.
3268 * - Given an integer variable \f$x\f$ with fractional solution value \f$x^*\f$, the method
3269 * SCIPbranchVarVal() creates two child nodes; one contains the bound \f$x \le \lfloor x^* \rfloor\f$ and the other
3270 * one contains the bound \f$x \ge \lceil x^* \rceil\f$.
3271 * - Given an integer variable \f$x\f$ with integral solution value \f$x^*\f$, the method SCIPbranchVarVal()
3272 * creates three child nodes; one contains the bound \f$x \le x^* -1\f$, one contains the bound \f$x \ge x^* +1\f$,
3273 * one contains the fixing \f$x = x^*\f$.
3274 *
3275 * See the BRANCHEXECEXT callback in src/scip/branch_random.c for an example. In addition, if a proven lower bound of a
3276 * created child node is known the user may call the method SCIPupdateNodeLowerbound() in order to update the child
3277 * node's lower bound.
3278 *
3279 * Please also see the \ref BRANCHEXEC "further information for the three execution methods".
3280 *
3281 * @subsection BRANCHEXECPS
3282 *
3283 * The BRANCHEXECPS callback is executed during node processing if no LP solution is available and at least one of the
3284 * integer variables is not yet fixed. It should split the current problem into smaller subproblems. PS stands for
3285 * pseudo solution which is the vector of all variables set to their locally best (w.r.t. the objective function)
3286 * bounds.
3287 *
3288 * The user gains access to the branching candidates, i.e., to the non-fixed integer variables, by calling the method
3289 * SCIPgetPseudoBranchCands(). Furthermore, SCIP provides two methods for performing the actual branching, namely
3290 * SCIPbranchVar() and SCIPcreateChild().
3291 *
3292 * Given an integer variable \f$x\f$ with bounds \f$[l,u]\f$ and not having solved the LP, the method SCIPbranchVar()
3293 * creates two child nodes:
3294 * - If both bounds are finite, then the two children will contain the domain reductions \f$x \le x^*\f$, and \f$x \ge
3295 * x^*+1\f$ with \f$x^* = \lfloor \frac{l + u}{2}\rfloor\f$. The current pseudo solution will remain feasible in one
3296 * of the branches, but the hope is that halving the domain's size leads to good propagations.
3297 * - If only one of the bounds is finite, the variable will be fixed to that bound in one of the child nodes. In the
3298 * other child node, the bound will be shifted by one.
3299 * - 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$.
3300
3301 *
3302 * See the BRANCHEXECPS callback in src/scip/branch_random.c for an example. In addition, if a proven lower bound of a
3303 * created child node is known, the user may call the method SCIPupdateNodeLowerbound() in order to update the child
3304 * node's lower bound.
3305 *
3306 * Please also see the \ref BRANCHEXEC "further information for the three execution methods".
3307 *
3308 * @subsection BRANCHEXEC Further information for the three execution methods
3309 *
3310 * In order to apply more general branching schemes, one should use the method SCIPcreateChild().
3311 * After having created a child node, the additional restrictions of the child node have to be added with calls to
3312 * SCIPaddConsNode(), SCIPchgVarLbNode(), or SCIPchgVarUbNode().
3313 * \n
3314 * In the method SCIPcreateChild(), the branching rule has to assign two values to the new nodes: a node selection
3315 * priority for each node and an estimate for the objective value of the best feasible solution contained in the subtree
3316 * after applying the branching. If the method SCIPbranchVar() is used, these values are automatically assigned. For
3317 * variable based branching schemes, one might use the methods SCIPcalcNodeselPriority() and the method
3318 * SCIPcalcChildEstimate().
3319 *
3320 * In some cases, the branching rule can tighten the current subproblem instead of producing a branching. For example,
3321 * strong branching might have proven that rounding up a variable would lead to an infeasible LP relaxation and thus,
3322 * the variable must be rounded down. Therefore, the BRANCHEXECLP, BRANCHEXECPS and BRANCHEXECREL callbacks may also
3323 * produce domain reductions or add additional constraints to the current subproblem.
3324 *
3325 * The execution callbacks have the following options:
3326 * - detecting that the node is infeasible and can be cut off (result SCIP_CUTOFF)
3327 * - adding an additional constraint (e.g. a conflict constraint) (result SCIP_CONSADDED; note that this action
3328 * must not be performed if the input "allowaddcons" is FALSE)
3329 * - reducing the domain of a variable such that the current LP solution becomes infeasible (result SCIP_REDUCEDDOM)
3330 * - applying a branching (result SCIP_BRANCHED)
3331 * - stating that the branching rule was skipped (result SCIP_DIDNOTRUN).
3332 *
3333 * Only the BRANCHEXECLP callback has the possibility to add a cutting plane to the LP (result SCIP_SEPARATED).
3334 *
3335 * @subsection BRANCHFREE
3336 *
3337 * If you are using branching rule data, you have to implement this method in order to free the branching rule data.
3338 * This can be done by the following procedure:
3339 *
3340 * @refsnippet{src/scip/branch_random.c,SnippetBranchFreeRandom}
3341 *
3342 * If you have allocated memory for fields in your branching rule data, remember to free this memory
3343 * before freeing the branching rule data itself.
3344 * If you are using the C++ wrapper class, this method is not available.
3345 * Instead, just use the destructor of your class to free the member variables of your class.
3346 *
3347 * @subsection BRANCHINIT
3348 *
3349 * The BRANCHINIT callback is executed after the problem is transformed.
3350 * The branching rule may, e.g., use this call to initialize its branching rule data.
3351 *
3352 * @subsection BRANCHCOPY
3353 *
3354 * The BRANCHCOPY callback is executed when a SCIP instance is copied, e.g. to
3355 * solve a sub-SCIP. By
3356 * defining this callback as
3357 * <code>NULL</code> the user disables the execution of the specified
3358 * branching rule for all copied SCIP instances. This may deteriorate the performance
3359 * of primal heuristics using sub-SCIPs.
3360 *
3361 * @subsection BRANCHEXIT
3362 *
3363 * The BRANCHEXIT callback is executed before the transformed problem is freed.
3364 * In this method, the branching rule should free all resources that have been allocated for the solving process in
3365 * BRANCHINIT.
3366 *
3367 * @subsection BRANCHINITSOL
3368 *
3369 * The BRANCHINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3370 * begin.
3371 * The branching rule may use this call to initialize its branch-and-bound specific data.
3372 *
3373 * @subsection BRANCHEXITSOL
3374 *
3375 * The BRANCHEXITSOL callback is executed before the branch-and-bound process is freed.
3376 * The branching rule should use this call to clean up its branch-and-bound data.
3377 */
3378
3379
3380/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3381
3382/**@page CUTSEL How to add cut selectors
3383 *
3384 * Cut selectors are used to select the cuts that are going to be added to the relaxation.
3385 * For more information on how SCIP manages cuts, see "What is the difference between a sepastore and the cutpool?" in the
3386 * \ref FAQ.
3387 * \n
3388 * A complete list of all cut selectors contained in this release can be found \ref CUTSELECTORS "here".
3389 *
3390 * We now explain how users can add their own cut selectors.
3391 * Take the hybrid cut selector (src/scip/cutsel_hybrid.c) as an example.
3392 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjCutsel wrapper
3393 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_CUTSEL... callback methods.
3394 *
3395 * Additional documentation for the callback methods of a cut selector can be found in the file type_cutsel.h.
3396 *
3397 * Here is what you have to do to implement a cut selector:
3398 * -# Copy the template files src/scip/cutsel_xyz.c and src/scip/cutsel_xyz.h into files named "cutsel_mycutselector.c"
3399 * and "cutsel_mycutselector.h".
3400 * \n
3401 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
3402 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
3403 * -# Use SCIPincludeCutselMycutselector() in order to include the cut selector into your SCIP instance,
3404 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
3405 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
3406 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mycutselector".
3407 * -# Adjust the properties of the cut selector (see \ref CUTSEL_PROPERTIES).
3408 * -# Define the cut selector data (see \ref CUTSEL_DATA). This is optional.
3409 * -# Implement the interface methods (see \ref CUTSEL_INTERFACE).
3410 * -# Implement the fundamental callback methods (see \ref CUTSEL_FUNDAMENTALCALLBACKS).
3411 * -# Implement the additional callback methods (see \ref CUTSEL_ADDITIONALCALLBACKS). This is optional.
3412 *
3413 *
3414 * @section CUTSEL_PROPERTIES Properties of a Cut Selector
3415 *
3416 * At the top of the new file "cutsel_mycutselector.c" you can find the cut selector properties.
3417 * These are given as compiler defines.
3418 * In the C++ wrapper class, you have to provide the cut selector properties by calling the constructor
3419 * of the abstract base class scip::ObjCutsel from within your constructor.
3420 * The properties you have to set have the following meaning:
3421 *
3422 * \par CUTSEL_NAME: the name of the cut selector.
3423 * This name is used in the interactive shell to address the cut selector.
3424 * Additionally, if you are searching for a cut selector with SCIPfindCutsel(), this name is looked up.
3425 * Names have to be unique: no two cut selectors may have the same name.
3426 *
3427 * \par CUTSEL_DESC: the description of the cut selector.
3428 * This string is printed as a description of the cut selector in the interactive shell.
3429 *
3430 * \par CUTSEL_PRIORITY: the priority of the cut selector.
3431 * After all cuts have been collected in the sepastore, SCIP asks the cut selectors to select cuts.
3432 * The cut selectors are sorted by priority (highest goes first) and are called, in this order, until the first one
3433 * succeeds.
3434 * \n
3435 * Note that this property only defines the default value of the priority. The user may change this value arbitrarily by
3436 * adjusting the corresponding parameter setting. Whenever, even during solving, the priority of a cut selector is
3437 * changed, the cut selectors are resorted by the new priorities.
3438 *
3439 *
3440 * @section CUTSEL_DATA Cut Selector Data
3441 *
3442 * Below the header "Data structures" you can find a struct which is called "struct SCIP_CutselData".
3443 * In this data structure, you can store the data of your cut selector. For example, you should store the adjustable
3444 * parameters of the cut selector in this data structure.
3445 * If you are using C++, you can add cut selector data as usual as object variables to your class.
3446 * \n
3447 * Defining cut selector data is optional. You can leave the struct empty.
3448 *
3449 *
3450 * @section CUTSEL_INTERFACE Interface Methods
3451 *
3452 * At the bottom of "cutsel_mycutselector.c", you can find the interface method SCIPincludeCutselMycutselector(),
3453 * which also appears in "cutsel_mycutselector.h"
3454 * SCIPincludeCutselMycutselector() is called by the user, if they want to include the cut selector, i.e., if they want
3455 * to use the cut selector in their application.
3456 *
3457 * This method only has to be adjusted slightly.
3458 * It is responsible for notifying SCIP of the presence of the cut selector. For this, you can either call
3459 * SCIPincludeCutsel()
3460 * or SCIPincludeCutselBasic(). In the latter variant, \ref CUTSEL_ADDITIONALCALLBACKS "additional callbacks"
3461 * must be added via setter functions as, e.g., SCIPsetCutselCopy(). We recommend this latter variant because
3462 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3463 * variant must be manually adjusted with every SCIP release containing new callbacks for cut selectors in order to compile.
3464 *
3465 *
3466 * If you are using cut selector data, you have to allocate the memory for the data at this point.
3467 * You can do this by calling:
3468 * \code
3469 * SCIP_CALL( SCIPallocBlockMemory(scip, &cutseldata) );
3470 * \endcode
3471 * You also have to initialize the fields in struct SCIP_CutselData afterwards.
3472 *
3473 * You may also add user parameters for your cut selector, see the method SCIPincludeCutselHybrid() in
3474 * src/scip/cutsel_hybrid.c for an example.
3475 *
3476 *
3477 * @section CUTSEL_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Cut Selector
3478 *
3479 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
3480 * an operational algorithm.
3481 * They are passed together with the cut selector itself to SCIP using SCIPincludeCutsel() or SCIPincludeCutselBasic(),
3482 * see @ref CUTSEL_INTERFACE.
3483 *
3484 * Cut selector plugins have a single fundamental callback method, namely the CUTSELSELECT method.
3485 * This method has to be implemented for every cut selector; the other callback methods are optional.
3486 * It implements the single contribution every selector has to provide: Selecting cuts to be added to the relaxation.
3487 * In the C++ wrapper class scip::ObjCutsel, the scip_select() method is a virtual abstract member function.
3488 * You have to implement it in order to be able to construct an object of your cut selector class.
3489 *
3490 * @subsection CUTSELSELECT
3491 *
3492 * The CUTSELSELECT callback should decide which cuts should be added to the relaxation.
3493 * The callback receives the arrays of cuts to select from. This array must be resorted and the first nselectedcuts from
3494 * the sorted array are going to be selected.
3495 * In addition to the aforementioned cuts, the list of forced cuts is also given as an argument. This array can be used
3496 * to help with the selection algorithm. Note, however, that this array should not be tampered with.
3497 *
3498 * Additional documentation for this callback can be found in type_cutsel.h.
3499 *
3500 * @section CUTSEL_ADDITIONALCALLBACKS Additional Callback Methods of a Cut Selector
3501 *
3502 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
3503 * implemented for most applications. They can be used, for example, to initialize and free private data.
3504 * Additional callbacks can either be passed directly with SCIPincludeCutsel() to SCIP or via specific
3505 * <b>setter functions</b> after a call of SCIPincludeCutselBasic(), see also @ref CUTSEL_INTERFACE.
3506 *
3507 * @subsection CUTSELFREE
3508 *
3509 * If you are using cut selector data, you have to implement this method in order to free the cut selector data.
3510 * This can be done by the following procedure:
3511 *
3512 * @refsnippet{src/scip/cutsel_hybrid.c,SnippetCutselFreeHybrid}
3513 *
3514 * If you have allocated memory for fields in your cut selector data, remember to free this memory
3515 * before freeing the cut selector data itself.
3516 * If you are using the C++ wrapper class, this method is not available.
3517 * Instead, just use the destructor of your class to free the member variables of your class.
3518 *
3519 * @subsection CUTSELINIT
3520 *
3521 * The CUTSELINIT callback is executed after the problem is transformed.
3522 * The cut selector may, for example, use this call to initialize its cut selector data.
3523 *
3524 * @subsection CUTSELCOPY
3525 *
3526 * The CUTSELCOPY callback is executed when a SCIP instance is copied, e.g., to solve a sub-SCIP. By defining this
3527 * callback as <code>NULL</code> the user disables the execution of the specified cut selector for all copied SCIP
3528 * instances.
3529 *
3530 * @subsection CUTSELEXIT
3531 *
3532 * The CUTSELEXIT callback is executed before the transformed problem is freed.
3533 * In this method, the cut selector should free all resources that have been allocated for the solving process
3534 * in CUTSELINIT.
3535 *
3536 * @subsection CUTSELINITSOL
3537 *
3538 * The CUTSELINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3539 * begin.
3540 * The cut selector may use this call to initialize its branch-and-bound specific data.
3541 *
3542 * @subsection CUTSELEXITSOL
3543 *
3544 * The CUTSELEXITSOL callback is executed before the branch-and-bound process is freed.
3545 * The cut selector should use this call to clean up its branch-and-bound data.
3546 */
3547
3548/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3549
3550/**@page NODESEL How to add node selectors
3551 *
3552 * Node selectors are used to decide which of the leaves in the current branching tree is selected as next subproblem
3553 * to be processed. The ordering relation of the tree's leaves for storing them in the leaf priority queue is also
3554 * defined by the node selectors.
3555 * \n
3556 * A complete list of all node selectors contained in this release can be found \ref NODESELECTORS "here".
3557 *
3558 * We now explain how users can add their own node selectors.
3559 * Take the node selector for depth first search (src/scip/nodesel_dfs.c) as an example.
3560 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjNodesel wrapper
3561 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_NODESEL... callback methods.
3562 *
3563 * Additional documentation for the callback methods of a node selector can be found in the file type_nodesel.h.
3564 *
3565 * Here is what you have to do to implement a node selector:
3566 * -# Copy the template files src/scip/nodesel_xyz.c and src/scip/nodesel_xyz.h into files named "nodesel_mynodeselector.c"
3567 * and "nodesel_mynodeselector.h".
3568 * \n
3569 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
3570 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
3571 * -# Use SCIPincludeNodeselMynodeselector() in order to include the node selector into your SCIP instance,
3572 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
3573 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
3574 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mynodeselector".
3575 * -# Adjust the properties of the node selector (see \ref NODESEL_PROPERTIES).
3576 * -# Define the node selector data (see \ref NODESEL_DATA). This is optional.
3577 * -# Implement the interface methods (see \ref NODESEL_INTERFACE).
3578 * -# Implement the fundamental callback methods (see \ref NODESEL_FUNDAMENTALCALLBACKS).
3579 * -# Implement the additional callback methods (see \ref NODESEL_ADDITIONALCALLBACKS). This is optional.
3580 *
3581 *
3582 * @section NODESEL_PROPERTIES Properties of a Node Selector
3583 *
3584 * At the top of the new file "nodesel_mynodeselector.c" you can find the node selector properties.
3585 * These are given as compiler defines.
3586 * In the C++ wrapper class, you have to provide the node selector properties by calling the constructor
3587 * of the abstract base class scip::ObjNodesel from within your constructor.
3588 * The properties you have to set have the following meaning:
3589 *
3590 * \par NODESEL_NAME: the name of the node selector.
3591 * This name is used in the interactive shell to address the node selector.
3592 * Additionally, if you are searching for a node selector with SCIPfindNodesel(), this name is looked up.
3593 * Names have to be unique: no two node selectors may have the same name.
3594 *
3595 * \par NODESEL_DESC: the description of the node selector.
3596 * This string is printed as a description of the node selector in the interactive shell.
3597 *
3598 * \par NODESEL_STDPRIORITY: the default priority of the node selector in the standard mode.
3599 * The first step of each iteration of the main solving loop is the selection of the next subproblem to be processed.
3600 * The node selector of highest priority (the active node selector) is called to do this selection.
3601 * In particular, if you implemented your own node selector plugin which you want to be applied, you should choose a priority
3602 * which is greater then all priorities of the SCIP default node selectors.
3603 * Note that SCIP has two different operation modes: the standard mode and the memory saving mode. If the memory
3604 * limit - given as a parameter by the user - is almost reached, SCIP switches from the standard mode to the memory saving
3605 * mode in which different priorities for the node selectors are applied. NODESEL_STDPRIORITY is the priority of the
3606 * node selector used in the standard mode.
3607 * \n
3608 * Note that this property only defines the default value of the priority. The user may change this value arbitrarily by
3609 * adjusting the corresponding parameter setting.
3610 *
3611 * \par NODESEL_MEMSAVEPRIORITY: the default priority of the node selector in the memory saving mode.
3612 * The priority NODESEL_MEMSAVEPRIORITY of the node selector has the same meaning as the priority NODESEL_STDPRIORITY, but
3613 * is used in the memory saving mode.
3614 * Usually, you want the best performing node selector, for example best estimate search, to have maximal
3615 * standard priority, while you want a node selector which tends to keep the growth of the search tree limited, for example
3616 * depth first search, to have maximal memory saving priority.
3617 * \n
3618 * Note that this property only defines the default value of the priority. The user may change this value arbitrarily by
3619 * adjusting the corresponding parameter setting.
3620 *
3621 *
3622 * @section NODESEL_DATA Node Selector Data
3623 *
3624 * Below the header "Data structures" you can find a struct which is called "struct SCIP_NodeselData".
3625 * In this data structure, you can store the data of your node selector. For example, you should store the adjustable
3626 * parameters of the node selector in this data structure.
3627 * If you are using C++, you can add node selector data as usual as object variables to your class.
3628 * \n
3629 * Defining node selector data is optional. You can leave the struct empty.
3630 *
3631 *
3632 * @section NODESEL_INTERFACE Interface Methods
3633 *
3634 * At the bottom of "nodesel_mynodeselector.c", you can find the interface method SCIPincludeNodeselMynodeselector(),
3635 * which also appears in "nodesel_mynodeselector.h"
3636 * SCIPincludeNodeselMynodeselector() is called by the user, if (s)he wants to include the node selector,
3637 * i.e., if (s)he wants to use the node selector in his/her application.
3638 *
3639 * This method only has to be adjusted slightly.
3640 * It is responsible for notifying SCIP of the presence of the node selector. For this, you can either call
3641 * SCIPincludeNodesel(),
3642 * or SCIPincludeNodeselBasic() since SCIP version 3.0. In the latter variant, \ref NODESEL_ADDITIONALCALLBACKS "additional callbacks"
3643 * must be added via setter functions as, e.g., SCIPsetNodeselCopy(). We recommend this latter variant because
3644 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3645 * variant must be manually adjusted with every SCIP release containing new callbacks for node selectors in order to compile.
3646 *
3647 *
3648 * If you are using node selector data, you have to allocate the memory for the data at this point.
3649 * You can do this by calling:
3650 * \code
3651 * SCIP_CALL( SCIPallocBlockMemory(scip, &nodeseldata) );
3652 * \endcode
3653 * You also have to initialize the fields in struct SCIP_NodeselData afterwards.
3654 *
3655 * You may also add user parameters for your node selector, see the method SCIPincludeNodeselRestartdfs() in
3656 * src/scip/nodesel_restartdfs.c for an example.
3657 *
3658 *
3659 * @section NODESEL_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Node Selector
3660 *
3661 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
3662 * an operational algorithm.
3663 * They are passed together with the node selector itself to SCIP using SCIPincludeNodesel() or SCIPincludeNodeselBasic(),
3664 * see @ref NODESEL_INTERFACE.
3665 *
3666 * Node selector plugins have two fundamental callback methods, namely the NODESELSELECT method and the NODESELCOMP method.
3667 * These methods have to be implemented for every node selector; the other callback methods are optional.
3668 * They implement the two requirements every node selector has to fulfill: Selecting a node from the queue to be processed
3669 * next and, given two nodes, deciding which of both is favored by the node selector's selection rule. The first
3670 * task is implemented in the NODESELSELECT callback, the second one in the NODESELCOMP callback.
3671 * In the C++ wrapper class scip::ObjNodesel, the scip_select() method and the scip_comp() method (which correspond to the
3672 * NODESELSELECT callback and the NODESELCOMP callback, respectively) are virtual abstract member functions.
3673 * You have to implement them in order to be able to construct an object of your node selector class.
3674 *
3675 * Additional documentation for the callback methods can be found in type_nodesel.h.
3676 *
3677 * @subsection NODESELSELECT
3678 *
3679 * The NODESELSELECT callback is the first method called in each iteration in the main solving loop. It should decide
3680 * which of the leaves in the current branching tree is selected as the next subproblem to be processed.
3681 * It can arbitrarily decide between all leaves stored in the tree, but for performance reasons,
3682 * the current node's children and siblings are often treated different from the remaining leaves.
3683 * This is mainly due to the warm start capabilities of the simplex algorithm and the expectation that the bases of
3684 * neighboring vertices in the branching tree very similar.
3685 * The node selector's choice of the next node to process can
3686 * have a large impact on the solver's performance, because it influences the finding of feasible solutions and the
3687 * development of the global dual bound.
3688 *
3689 * Besides the ranking of the node selector, every node gets assigned a node selection priority by the branching rule
3690 * that created the node. See the \ref BRANCHEXECLP and \ref BRANCHEXECPS callbacks of the branching rules for details.
3691 * For example, the node where the branching went in the same way as the deviation from the branching variable's
3692 * root solution could be assigned a higher priority than the node where the branching went in the opposite direction.
3693 *
3694 * The following methods provide access to the various types of leaf nodes:
3695 * - SCIPgetPrioChild() returns the child of the current node with the largest node selection priority, as assigned by the
3696 * branching rule.
3697 * If no child is available (for example, because the current node was pruned), a NULL pointer is returned.
3698 * - SCIPgetBestChild() returns the best child of the current node with respect to the node selector's ordering relation as
3699 * defined by the \ref NODESELCOMP callback. If no child is available, a NULL pointer is returned.
3700 * - SCIPgetPrioSibling() returns the sibling of the current node with the largest node selection priority.
3701 * If no sibling is available (for example, because all siblings of the current node have already been processed), a NULL
3702 * pointer is returned.
3703 * Note that in binary branching every node has at most one sibling, but since SCIP supports arbitrary branching rules,
3704 * this might not always be the case.
3705 * - SCIPgetBestSibling() returns the best sibling of the current node with respect to the node selector's ordering relation
3706 * as defined by the \ref NODESELCOMP callback. If no sibling is available, a NULL pointer is returned.
3707 * - SCIPgetBestNode() returns the best leaf from the tree (children, siblings, or other leaves) with respect to the node
3708 * selector's ordering relation as defined by the \ref NODESELCOMP callback. If no open leaf exists, a NULL pointer is
3709 * returned. In this case, the optimization is finished, and the node selector should return a NULL pointer as 'selnode'.
3710 * - SCIPgetBestboundNode() returns a leaf from the tree (children, siblings, or other leaves) with the smallest lower (dual)
3711 * objective bound. If the queue is empty, a NULL pointer is returned. In this case, the optimization is finished, and the
3712 * node selector should return a NULL pointer as 'selnode'.
3713 *
3714 *
3715 * @subsection NODESELCOMP
3716 *
3717 * The NODESELCOMP callback is called to compare two leaves of the current branching tree (say node 1 and node 2)
3718 * regarding their ordering relation.
3719 *
3720 * The NODESELCOMP should return the following values:
3721 * - value < 0, if node 1 comes before (is better than) node 2
3722 * - value = 0, if both nodes are equally good
3723 * - value > 0, if node 1 comes after (is worse than) node 2.
3724 *
3725 * @section NODESEL_ADDITIONALCALLBACKS Additional Callback Methods of a Node Selector
3726 *
3727 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
3728 * implemented for most applications, they can be used, for example, to initialize and free private data.
3729 * Additional callbacks can either be passed directly with SCIPincludeNodesel() to SCIP or via specific
3730 * <b>setter functions</b> after a call of SCIPincludeNodeselBasic(), see also @ref NODESEL_INTERFACE.
3731 *
3732 * @subsection NODESELFREE
3733 *
3734 * If you are using node selector data, you have to implement this method in order to free the node selector data.
3735 * This can be done by the following procedure:
3736 *
3737 * @refsnippet{src/scip/nodesel_bfs.c,SnippetNodeselFreeBfs}
3738 *
3739 * If you have allocated memory for fields in your node selector data, remember to free this memory
3740 * before freeing the node selector data itself.
3741 * If you are using the C++ wrapper class, this method is not available.
3742 * Instead, just use the destructor of your class to free the member variables of your class.
3743 *
3744 * @subsection NODESELINIT
3745 *
3746 * The NODESELINIT callback is executed after the problem is transformed.
3747 * The node selector may, e.g., use this call to initialize its node selector data.
3748 *
3749 * @subsection NODESELCOPY
3750 *
3751 * The NODESELCOPY callback is executed when a SCIP instance is copied, e.g. to
3752 * solve a sub-SCIP. By
3753 * defining this callback as
3754 * <code>NULL</code> the user disables the execution of the specified
3755 * node selector for all copied SCIP instances. This may deteriorate the performance
3756 * of primal heuristics using sub-SCIPs.
3757 *
3758 * @subsection NODESELEXIT
3759 *
3760 * The NODESELEXIT callback is executed before the transformed problem is freed.
3761 * In this method, the node selector should free all resources that have been allocated for the solving process
3762 * in NODESELINIT.
3763 *
3764 * @subsection NODESELINITSOL
3765 *
3766 * The NODESELINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3767 * begin.
3768 * The node selector may use this call to initialize its branch-and-bound specific data.
3769 *
3770 * @subsection NODESELEXITSOL
3771 *
3772 * The NODESELEXITSOL callback is executed before the branch-and-bound process is freed.
3773 * The node selector should use this call to clean up its branch-and-bound data.
3774 */
3775
3776
3777/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3778
3779/**@page HEUR How to add primal heuristics
3780 *
3781 * Feasible solutions can be found in two different ways during the traversal of the branch-and-bound tree. On one
3782 * hand, the solution of a node's relaxation may be feasible with respect to the constraints (including the integrality).
3783 * On the other hand, feasible solutions can be discovered by primal heuristics.
3784 * \n
3785 * A complete list of all primal heuristics contained in this release can be found \ref PRIMALHEURISTICS "here".
3786 * \n
3787 * Diving heuristics are primal heuristics that explore an auxiliary search tree in a depth-first manner. Since SCIP
3788 * version 3.2, it is easy to integrate further diving heuristics by using a special controller for the scoring,
3789 * see \ref DIVINGHEUR "here" for information on how to implement a diving heuristic.
3790 * \n
3791 * We now explain how users can add their own primal heuristics.
3792 * Take the simple and fast LP rounding heuristic (src/scip/heur_simplerounding.c) as an example.
3793 * The idea of simple rounding is to iterate over all fractional variables of an LP solution and round them down,
3794 * if the variables appears only with nonnegative coefficients in the system Ax <= b and round them up if
3795 * the variables appears only with nonpositive coefficients.
3796 * If one of both conditions applies for each of the fractional variables, this will give a feasible solution.
3797 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjHeur wrapper
3798 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_HEUR... callback methods.
3799 *
3800 * Additional documentation for the callback methods of a primal heuristic can be found in the file type_heur.h.
3801 *
3802 * Here is what you have to do to implement a primal heuristic:
3803 * -# Copy the template files src/scip/heur_xyz.c and src/scip/heur_xyz.h into files named "heur_myheuristic.c"
3804 * and "heur_myheuristic.h".
3805 * \n
3806 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
3807 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
3808 * -# Use `SCIPincludeHeurMyheuristic()` in order to include the heuristic into your SCIP instance,
3809 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
3810 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
3811 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myheuristic".
3812 * -# Adjust the properties of the primal heuristic (see \ref HEUR_PROPERTIES).
3813 * -# Define the primal heuristic data (see \ref HEUR_DATA). This is optional.
3814 * -# Implement the interface methods (see \ref HEUR_INTERFACE).
3815 * -# Implement the fundamental callback methods (see \ref HEUR_FUNDAMENTALCALLBACKS).
3816 * -# Implement the additional callback methods (see \ref HEUR_ADDITIONALCALLBACKS). This is optional.
3817 *
3818 *
3819 * @section HEUR_PROPERTIES Properties of a Primal Heuristic
3820 *
3821 * At the top of the new file "heur_myheuristic.c" you can find the primal heuristic properties.
3822 * These are given as compiler defines.
3823 * In the C++ wrapper class, you have to provide the primal heuristic properties by calling the constructor
3824 * of the abstract base class scip::ObjHeur from within your constructor.
3825 * Of course, all of them are of relevant, but the most important ones for controlling the performance
3826 * are usually HEUR_FREQ and HEUR_TIMING.
3827 * The properties you have to set have the following meaning:
3828 *
3829 * \par HEUR_NAME: the name of the primal heuristic.
3830 * This name is used in the interactive shell to address the primal heuristic.
3831 * Additionally, if you are searching for a primal heuristic with SCIPfindHeur(), this name is looked up.
3832 * Names have to be unique: no two primal heuristics may have the same name.
3833 *
3834 * \par HEUR_DESC: the description of the primal heuristic.
3835 * This string is printed as a description of the primal heuristic in the interactive shell when you call "display heuristics".
3836 *
3837 * \par HEUR_DISPCHAR: the display character of the primal heuristic.
3838 * In the interactive shell, this character is printed in the first column of a status information row, if the primal
3839 * heuristic found the feasible solution belonging to the primal bound. Note that a star '*' stands for an integral
3840 * LP-relaxation.
3841 * It is recommended to select a lower or upper case letter as display character. The default primal heuristics of
3842 * SCIP use characters that describe the class to which the heuristic belongs. As an example all LP rounding heuristics
3843 * have an 'r' and all Large Neighborhood Search heuristics use the letter 'L'.
3844 * Users find commonly used display characters in type_heur.h.
3845 *
3846 *
3847 * \par HEUR_PRIORITY: the priority of the primal heuristic.
3848 * At each of the different entry points of the primal heuristics during the solving process (see HEUR_TIMING), they are
3849 * called in decreasing order of their priority.
3850 * \n
3851 * The priority of a primal heuristic should be set according to the complexity of the heuristic and the likelihood to find
3852 * feasible solutions: primal heuristics that provide fast algorithms that often succeed in finding a feasible solution should have
3853 * a high priority (like simple rounding). In addition, the interaction between different types of primal heuristics should be taken into account.
3854 * For example, improvement heuristics, which try to generate improved solutions by inspecting one or more of the feasible
3855 * solutions that have already been found, should have a low priority (like Crossover which by default needs at least 3 feasible solutions).
3856 *
3857 * \par HEUR_FREQ: the default frequency for executing the primal heuristic.
3858 * The frequency together with the frequency offset (see HEUR_FREQOFS) defines the depth levels at which the execution
3859 * method of the primal heuristic \ref HEUREXEC is called. For example, a frequency of 7 together with a frequency offset
3860 * of 5 means, that the \ref HEUREXEC callback is executed for subproblems that are in depth 5, 12, 19, ... of the branching tree. A
3861 * frequency of 0 together with a frequency offset of 3 means, that the execution method is only called at those nodes that are in
3862 * depth level 3 (i.e., at most for \f$2^3 = 8\f$ nodes if binary branching is applied).
3863 * Typical cases are: A frequency of 0 and an offset of 0 which means that
3864 * the heuristic is only called at the root node and a frequency of -1 which disables the heuristic.
3865 * \n
3866 * The frequency can be adjusted by the user. This property of the primal heuristic only defines the default value of the
3867 * frequency. If you want to have a more flexible control of when to execute the primal heuristic, you have to assign
3868 * a frequency of 1 and implement a check at the beginning of your execution method whether you really want to search for feasible
3869 * solutions or not. If you do not want to execute the method, set the result code to SCIP_DIDNOTRUN.
3870 *
3871 * \par HEUR_FREQOFS: the frequency offset for executing the primal heuristic.
3872 * The frequency offset defines the depth of the branching tree at which the primal heuristic is executed for the first
3873 * time. For example, a frequency of 7 (see HEUR_FREQ) together with a frequency offset of 10 means, that the
3874 * callback is executed for subproblems that are in depth 10, 17, 24, ... of the branching tree. In particular, assigning
3875 * different offset values to heuristics of the same type, like diving heuristics, can be useful for evenly spreading the
3876 * application of these heuristics across the branch-and-bound tree.
3877 * Note that if the frequency is equal to 1, the heuristic is applied for all nodes with depth level larger or equal to
3878 * the frequency offset.
3879 *
3880 * \par HEUR_MAXDEPTH: the maximal depth level for executing the primal heuristic.
3881 * This parameter denotes the maximal depth level in the branching tree up to which the execution method of the primal
3882 * heuristic is called. Use -1 for no limit (a usual case).
3883 *
3884 * \par HEUR_TIMING: the execution timing of the primal heuristic.
3885 * Primal heuristics have different entry points during the solving process and the execution timing parameter defines the
3886 * entry point at which the primal heuristic is executed first.
3887 * \n
3888 * The primal heuristic can be called first:
3889 * - before the processing of the node starts (SCIP_HEURTIMING_BEFORENODE)
3890 * - after each LP solve during the cut-and-price loop (SCIP_HEURTIMING_DURINGLPLOOP)
3891 * - after the cut-and-price loop was finished (SCIP_HEURTIMING_AFTERLPLOOP)
3892 * - after the processing of a node <em>with solved LP</em> was finished (SCIP_HEURTIMING_AFTERLPNODE)
3893 * - after the processing of a node <em>without solved LP</em> was finished (SCIP_HEURTIMING_AFTERPSEUDONODE)
3894 * - after the processing of the last node in the current plunge was finished, <em>and only if the LP was solved for
3895 * this node</em> (SCIP_HEURTIMING_AFTERLPPLUNGE)
3896 * - after the processing of the last node in the current plunge was finished, <em>and only if the LP was not solved
3897 * for this node</em> (SCIP_HEURTIMING_AFTERPSEUDOPLUNGE).
3898 * \par
3899 * A plunge is the successive solving of child and sibling nodes in the search tree.
3900 * The flags listed above can be combined to call the heuristic at multiple times by concatenating them with a bitwise OR.
3901 * Two useful combinations are already predefined:
3902 * - after the processing of a node was finished (SCIP_HEURTIMING_AFTERNODE; combines SCIP_HEURTIMING_AFTERLPNODE and
3903 * SCIP_HEURTIMING_AFTERPSEUDONODE)
3904 * - after the processing of the last node in the current plunge was finished (SCIP_HEURTIMING_AFTERPLUNGE; combines
3905 * SCIP_HEURTIMING_AFTERLPPLUNGE and SCIP_HEURTIMING_AFTERPSEUDOPLUNGE)
3906 * \par
3907 * Calling a primal heuristic "before the processing of the node starts" is particularly useful for heuristics
3908 * that do not need to access the LP solution of the current node. If such a heuristic finds a feasible solution, the
3909 * leaves of the branching tree exceeding the new primal bound are pruned. It may happen that even the current node can
3910 * be cut off without solving the LP relaxation. Combinatorial heuristics, like the farthest insert heuristic for the TSP
3911 * (see examples/TSP/src/HeurFarthestInsert.cpp), are often applicable at this point.
3912 * \n
3913 * Very fast primal heuristics that require an LP solution can also be called "after each LP solve during the
3914 * cut-and-price loop". Rounding heuristics, like the simple and fast LP rounding heuristic
3915 * (src/scip/heur_simplerounding.c), belong to this group of primal heuristics.
3916 * \n
3917 * Most heuristics, however, are called either after a node was completely processed
3918 * (e.g. expensive rounding heuristics like RENS), or even only after a full plunge was finished (e.g., diving heuristics).
3919 *
3920 * \par HEUR_USESSUBSCIP: Does the heuristic use a secondary SCIP instance?
3921 * Some heuristics and separators solve MIPs or SAT problems using a secondary SCIP instance. Examples are
3922 * Large Neighborhood Search heuristics such as RINS and Local Branching or the CGMIP separator. To avoid recursion,
3923 * these plugins usually deactivate all other plugins that solve MIPs. If a heuristic uses a secondary SCIP instance,
3924 * this parameter has to be TRUE and it is recommended to call SCIPsetSubscipsOff() for the secondary SCIP instance.
3925 *
3926 * Computational experiments indicate that for the overall performance of a MIP solver, it is important to evenly
3927 * spread the application of the heuristics across the branch-and-bound tree. Thus, the assignment of the parameters
3928 * HEUR_FREQ, HEUR_FREQOFS, and HEUR_TIMING should contribute to this aim.
3929 *
3930 * Note that all diving heuristics in the SCIP distribution (see, e.g., src/scip/heur_guideddiving.c) check whether other diving
3931 * heuristics have already been called at the current node. This can be done by comparing SCIPgetLastDivenode(scip) and
3932 * SCIPgetNNodes(scip). If the two are equal, and if the current node is not the root node (SCIPgetDepth(scip) > 0), diving
3933 * heuristics should be delayed by returning the result code 'SCIP_DELAYED'. This is an additional contribution to the goal of
3934 * not calling multiple similar heuristics at the same node.
3935 *
3936 *
3937 * @section HEUR_DATA Primal Heuristic Data
3938 *
3939 * Below the header "Data structures" you can find a struct which is called "struct SCIP_HeurData".
3940 * In this data structure, you can store the data of your primal heuristic. For example, you should store the adjustable
3941 * parameters of the primal heuristic or a working solution in this data structure.
3942 * If you are using C++, you can add primal heuristic data as usual as object variables to your class.
3943 * \n
3944 * Defining primal heuristic data is optional. You can leave the struct empty.
3945 *
3946 *
3947 * @section HEUR_INTERFACE Interface Methods
3948 *
3949 * At the bottom of "heur_myheuristic.c", you can find the interface method SCIPincludeHeurMyheuristic(),
3950 * which also appears in "heur_myheuristic.h"
3951 * SCIPincludeHeurMyheuristic() is called by the user, if (s)he wants to include the heuristic,
3952 * i.e., if (s)he wants to use the heuristic in his/her application.
3953 *
3954 * This method only has to be adjusted slightly.
3955 * It is responsible for notifying SCIP of the presence of the heuristic. For this, you can either call
3956 * SCIPincludeHeur(),
3957 * or SCIPincludeHeurBasic() since SCIP version 3.0. In the latter variant, \ref HEUR_ADDITIONALCALLBACKS "additional callbacks"
3958 * must be added via setter functions as, e.g., SCIPsetHeurCopy(). We recommend this latter variant because
3959 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3960 * variant must be manually adjusted with every SCIP release containing new callbacks for heuristics in order to compile.
3961 *
3962 * If you are using primal heuristic data, you have to allocate the memory for the data at this point.
3963 * You can do this by calling:
3964 * \code
3965 * SCIP_CALL( SCIPallocBlockMemory(scip, &heurdata) );
3966 * \endcode
3967 * You also have to initialize the fields in struct SCIP_HeurData afterwards.
3968 *
3969 * You may also add user parameters for your primal heuristic, see the method SCIPincludeHeurFeaspump() in
3970 * src/scip/heur_oneopt.c for an example where a single Boolean parameter is added.
3971 *
3972 *
3973 * @section HEUR_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Primal Heuristic
3974 *
3975 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
3976 * an operational algorithm.
3977 * They are passed together with the primal heuristic itself to SCIP using SCIPincludeHeur() or SCIPincludeHeurBasic(),
3978 * see @ref HEUR_INTERFACE.
3979 *
3980 *
3981 * Primal heuristic plugins have only one fundamental callback method, namely the HEUREXEC method.
3982 * This method has to be implemented for every primal heuristic; the other callback methods are optional.
3983 * In the C++ wrapper class scip::ObjHeur, the scip_exec() method (which corresponds to the HEUREXEC callback) is a virtual
3984 * abstract member function. You have to implement it in order to be able to construct an object of your primal heuristic
3985 * class.
3986 *
3987 * Additional documentation for the callback methods can be found in type_heur.h.
3988 *
3989 * @subsection HEUREXEC
3990 *
3991 * The HEUREXEC callback is called at different positions during the node processing loop, see HEUR_TIMING. It should
3992 * search for feasible solutions and add them to the solution pool. For creating a new feasible solution, the
3993 * methods SCIPcreateSol() and SCIPsetSolVal() can be used. Afterwards, the solution can be added to the storage by
3994 * calling the method SCIPtrySolFree() (or SCIPtrySol() and SCIPfreeSol()).
3995 *
3996 * The HEUREXEC callback gets a SCIP pointer, a pointer to the heuristic itself, the current point in the
3997 * solve loop and a result pointer as input (see type_heur.h).
3998 *
3999 * The heuristic has to set the result pointer appropriately!
4000 * Therefore it has the following options:
4001 * - finding at least one feasible solution (result SCIP_FOUNDSOL)
4002 * - stating that the primal heuristic searched, but did not find a feasible solution (result SCIP_DIDNOTFIND)
4003 * - stating that the primal heuristic was skipped (result SCIP_DIDNOTRUN)
4004 * - stating that the primal heuristic was skipped, but should be called again (result SCIP_DELAYED).
4005 *
4006 *
4007 * @section HEUR_ADDITIONALCALLBACKS Additional Callback Methods of a Primal Heuristic
4008 *
4009 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
4010 * implemented for most applications, they can be used, for example, to initialize and free private data.
4011 * Additional callbacks can either be passed directly with SCIPincludeHeur() to SCIP or via specific
4012 * <b>setter functions</b> after a call of SCIPincludeHeurBasic(), see also @ref HEUR_INTERFACE.
4013 *
4014 * @subsection HEURFREE
4015 *
4016 * If you are using primal heuristic data, you have to implement this method in order to free the primal heuristic data.
4017 * This can be done by the following procedure:
4018 *
4019 * @refsnippet{applications/Coloring/src/heur_init.c,SnippetHeurFreeInit}
4020 *
4021 * If you have allocated memory for fields in your primal heuristic data, remember to free this memory
4022 * before freeing the primal heuristic data itself.
4023 * If you are using the C++ wrapper class, this method is not available.
4024 * Instead, just use the destructor of your class to free the member variables of your class.
4025 *
4026 * @subsection HEURINIT
4027 *
4028 * The HEURINIT callback is executed after the problem is transformed.
4029 * The primal heuristic may, e.g., use this call to initialize its primal heuristic data.
4030 *
4031 * @subsection HEURCOPY
4032 *
4033 * The HEURCOPY callback is executed when a SCIP instance is copied, e.g. to
4034 * solve a sub-SCIP. By
4035 * defining this callback as
4036 * <code>NULL</code> the user disables the execution of the specified
4037 * heuristic for all copied SCIP instances. This may deteriorate the performance
4038 * of primal heuristics using sub-SCIPs.
4039 *
4040 * @subsection HEUREXIT
4041 *
4042 * The HEUREXIT callback is executed before the tDIVINGHEURransformed problem is freed.
4043 * In this method, the primal heuristic should free all resources that have been allocated for the solving process in
4044 * HEURINIT.
4045 *
4046 * @subsection HEURINITSOL
4047 *
4048 * The HEURINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
4049 * begin. The primal heuristic may use this call to initialize its branch-and-bound specific data.
4050 *
4051 * @subsection HEUREXITSOL
4052 *
4053 * The HEUREXITSOL callback is executed before the branch-and-bound process is freed. The primal heuristic should use this
4054 * call to clean up its branch-and-bound data, which was allocated in HEURINITSOL.
4055 */
4056
4057/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4058
4059/**@page EXPRHDLR How to add expression handlers
4060 *
4061 * Expression handlers define basic expression types and provide additional functionality to work with expressions,
4062 * e.g., differentiation, simplification, estimation, hashing, copying, printing, parsing.
4063 * A complete list of all expression handlers contained in this release can be found \ref EXPRHDLRS "here".
4064 * In addition to expression handlers, higher level nonlinear structures are handled by nonlinear handlers, see \ref NLHDLR.
4065 *
4066 * Here is what you have to do to implement an own expression handler:
4067 * -# 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
4068 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
4069 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
4070 * -# Use `SCIPincludeExprhdlrMyfunc()` in order to include the expression handler into your SCIP instance,
4071 * e.g., in the main file of your project. \n
4072 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
4073 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myfunc".
4074 * -# Adjust the properties of the expression handler (see \ref EXPRHDLR_PROPERTIES).
4075 * -# Define the expression handler data and expression data (see \ref EXPRHDLR_DATA). This is optional.
4076 * -# Implement the interface methods (see \ref EXPRHDLR_INTERFACE).
4077 * -# Implement the fundamental callback methods (see \ref EXPRHDLR_FUNDAMENTALCALLBACKS).
4078 * -# Implement the additional callback methods (see \ref EXPRHDLR_ADDITIONALCALLBACKS), where necessary.
4079 *
4080 * Additional documentation for the callback methods of an expression handler, in particular for the input parameters,
4081 * can be found in the file \ref type_expr.h.
4082 *
4083 * For a complete implementation of an expression handler, take the one for exponential expressions (src/scip/expr_exp.c) as an example.
4084 *
4085 * @section EXPRHDLR_PROPERTIES Properties of an Expression Handler
4086 *
4087 * At the top of the new file `expr_myfunc.c`, you can find the expression handler properties.
4088 * These are given as compiler defines.
4089 * The properties you have to set have the following meaning:
4090 *
4091 * \par EXPRHDLR_NAME: the name of the expression handler.
4092 * This name is used in the interactive shell to address the expression handler.
4093 * Additionally, if you or a parsing routine is searching for an expression handler with SCIPfindExprhdlr(), this name is looked up.
4094 * Names have to be unique: no two expression handlers may have the same name.
4095 *
4096 * \par EXPRHDLR_DESC: the description of the expression handler.
4097 * This string is printed as a description of the expression handler in the interactive shell.
4098 *
4099 * \par EXPRHDLR_PRECEDENCE: the precedence of the expression handler.
4100 * Precedence of the expression operation relative to other expressions when printing the expression.
4101 *
4102 * @section EXPRHDLR_DATA Expression Handler Data and Expression Data
4103 *
4104 * Below the header "Data structures" you can find structs called `struct SCIP_ExprhdlrData` and `struct SCIP_ExprData`.
4105 * In this first data structure, you can store the data of your expression handler.
4106 * For example, you should store the adjustable parameters of the expression handler in this data structure.
4107 * In the second data structure, you can store data that is unique to an expression.
4108 * For example, the pow expression handler stores the exponent in this data structure.
4109 * \n
4110 * Defining expression handler data and expression data is optional. You can leave these structs empty.
4111 *
4112 * @section EXPRHDLR_INTERFACE Interface Methods
4113 *
4114 * @subsection EXPRHDLR_INCLUDE SCIPincludeExprhdlrMyfunc()
4115 *
4116 * At the bottom of `expr_myfunc.c`, you can find the interface method `SCIPincludeExprhdlrMyfunc()`,
4117 * which also appears in `expr_myfunc.h`.
4118 * `SCIPincludeExprhdlrMyfunc()` is called by the user, if (s)he wants to include the expression handler,
4119 * i.e., if (s)he wants to use the expression handler in his/her application.
4120 *
4121 * This method is responsible for notifying SCIP of the presence of the expression handler.
4122 * For this, you must call SCIPincludeExprhdlr() from SCIPincludeExprhdlrMyfunc().
4123 * The function only expects the properties and fundamental callbacks of the expression handler as arguments.
4124 * \ref EXPRHDLR_ADDITIONALCALLBACKS "Additional callbacks" must be added via setter functions as, e.g., SCIPexprhdlrSetCopyFreeHdlr().
4125 *
4126 * If you are using expression handler data, you have to allocate the memory for the data at this point.
4127 * You can do this by calling:
4128 * \code
4129 * SCIP_CALL( SCIPallocBlockMemory(scip, &exprhdlrdata) );
4130 * \endcode
4131 * You also have to initialize the fields in `struct SCIP_ExprhdlrData` afterwards.
4132 * For freeing the expression handler data, see \ref EXPRFREEHDLR.
4133 *
4134 * You may also add user parameters for your expression handler, see \ref PARAM for how to add user parameters.
4135 *
4136 * For the logarithm expression handler, the include method is as follows:
4137 * @refsnippet{src/scip/expr_log.c,SnippetIncludeExprhdlrLog}
4138 *
4139 * @subsection EXPRHDLR_CREATEEXPR SCIPcreateExprMyfunc()
4140 *
4141 * Another interface method that can be found in `expr_myfunc.c` is `SCIPcreateExprMyfunc()`.
4142 * This method is called by the user, if (s)he wants to create an expression that is handled by this expression handler.
4143 * Typically, the creation function takes the operands of the expression (the children) as arguments.
4144 * `SCIPcreateExprMyfunc()` may further be extended to take parameters of an expression into account.
4145 * For example, SCIPcreateExprPow() receives the exponent as argument.
4146 *
4147 * In the implementation of `SCIPcreateExprMyfunc()`, the expression data shall be allocated and initialized, if the expression has data
4148 * (like the exponent of pow expressions).
4149 * Then the expression shall be created by a call to SCIPcreateExpr().
4150 * This function takes the expression handler, expression data, children, and ownercreate callback as arguments.
4151 * For freeing the expression data, see \ref EXPRFREEDATA.
4152 *
4153 * The `ownercreate` and `ownercreatedata` that are passed to `SCIPcreateExprMyfunc()` need to be passed on to SCIP.
4154 * The owner of the expression that is created uses these arguments to store additional data in an expression.
4155 * For most usecases, these arguments will be set to `NULL`.
4156 * However, if the \ref EXPRPARSE callback is implemented, then `SCIPcreateExprMyfunc()` may need to be called with a non-NULL value
4157 * for `ownercreate` and `ownercreatedata`.
4158 * This will be the case if, for example, the constraint handler for nonlinear constraint parses an expression.
4159 * The constraint handler will then own the expression and needs to store some data in the expression.
4160 *
4161 * For the product expression handler, the expression create function is as follows:
4162 * @refsnippet{src/scip/expr_product.c,SnippetCreateExprProduct}
4163 *
4164 *
4165 * @section EXPRHDLR_FUNDAMENTALCALLBACKS Fundamental Callback Methods of an Expression Handler
4166 *
4167 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
4168 * an operational algorithm.
4169 * They are passed to SCIP when the expression handler is created and included in SCIP via SCIPincludeExprhdlr(),
4170 * see @ref EXPRHDLR_INTERFACE.
4171 *
4172 * Expression handlers have one fundamental callback, @ref EXPREVAL, that needs to be implemented.
4173 * However, expression handlers with stateful expressions (expressions that have data) need to implement also the
4174 * @ref EXPRCOPYDATA, @ref EXPRFREEDATA, and @ref EXPRCOMPARE callbacks.
4175 *
4176 * Additional documentation for the callback methods, in particular relating to their input parameters,
4177 * can be found in \ref type_expr.h.
4178 *
4179 * @subsection EXPREVAL
4180 *
4181 * The expression evaluation callback defines the mathematical operation that the expression handler represents.
4182 * Its purpose is to evaluate an expression by taking the values of its children (operands) into account.
4183 *
4184 * The children of the expression can be retrieved via SCIPexprGetChildren() and SCIPexprGetNChildren().
4185 * The value (a `SCIP_Real`) for each child can be retrieved via function SCIPexprGetEvalValue().
4186 * The value of the expression should be stored in the argument `val` that is passed to the callback.
4187 * For example, the evaluation in the expression handler for sum is doing the following:
4188 * @refsnippet{src/scip/expr_sum.c,SnippetExprEvalSum}
4189 *
4190 * When an expression cannot be evaluated w.r.t. the values of its children, such a domain error must be signaled
4191 * to SCIP by setting `*val` to `SCIP_INVALID`.
4192 * SCIP then aborts evaluation. It is thus not necessary to check in the evaluation callback whether any child
4193 * has value `SCIP_INVALID`.
4194 * For example, the evaluation in the expression handler for logarithm expressions is doing the following:
4195 * @refsnippet{src/scip/expr_log.c,SnippetExprEvalLog}
4196 *
4197 * The solution (`sol`) that is passed to EXPREVAL can usually be ignored.
4198 * It is used by the expression handler for variables to retrieve the value of a variable expression.
4199 *
4200 *
4201 * @section EXPRHDLR_ADDITIONALCALLBACKS Additional Callback Methods of an Expression Handler
4202 *
4203 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
4204 * implemented for most applications; they can be used, for example, to initialize and free private data.
4205 * Additional callbacks can be passed via specific
4206 * <b>setter functions</b> after a call of SCIPincludeExprhdlr(), see also @ref EXPRHDLR_INCLUDE.
4207 *
4208 * @subsection EXPRCOPYHDLR
4209 *
4210 * This method should include the expression handler into a given SCIP instance.
4211 * It is usually called when a copy of SCIP is generated.
4212 *
4213 * By not implementing this callback, the expression handler will not be available in copied SCIP instances.
4214 * If a nonlinear constraint uses expressions of this type, it will not be possible to copy them.
4215 * This may deteriorate the performance of primal heuristics using sub-SCIPs.
4216 *
4217 * @subsection EXPRFREEHDLR
4218 *
4219 * If you are using expression handler data (see \ref EXPRHDLR_DATA and \ref EXPRHDLR_INCLUDE), you have to implement this method
4220 * in order to free the expression handler data.
4221 *
4222 * @subsection EXPRCOPYDATA
4223 *
4224 * This method is called when creating copies of an expression within
4225 * the same or between different SCIP instances. It is given the
4226 * source expression, whose data shall be copied, and expects that
4227 * the data for the target expression is returned. This data will then be used
4228 * to create a new expression.
4229 *
4230 * If expressions that are handled by this expression handler have no data,
4231 * then this callback can be omitted.
4232 *
4233 * @subsection EXPRFREEDATA
4234 *
4235 * This method is called when freeing an expression that has data.
4236 * It is given an expression and shall free its expression data.
4237 * It shall then call `SCIPexprSetData(expr, NULL)`.
4238 *
4239 * This callback must be implemented for expressions that have data.
4240 *
4241 * @subsection EXPRPRINT
4242 *
4243 * This callback is called when an expression is printed.
4244 * It is called while DFS-iterating over the expression at different stages, that is,
4245 * when the expression is visited the first time, before each child of the expression is visited,
4246 * after each child of the expression has been visited, and when the iterator leaves the expression
4247 * for its parent.
4248 * At the various stages, the expression may print a string.
4249 * The given precedence of the parent expression can be used to decide whether parenthesis need to be printed.
4250 *
4251 * 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:
4252 * @refsnippet{src/scip/expr_pow.c,SnippetExprPrintPow}
4253 *
4254 * The pow expression handler does not yet take expression precedence into account to decide whether the parenthesis around `f(x)` can be omitted.
4255 * For the sum expression handler, this has been implemented:
4256 * @refsnippet{src/scip/expr_sum.c,SnippetExprPrintSum}
4257 *
4258 * If this callback is not implemented, the expression is printed as `<hdlrname>(<child1>, <child2>, ...)`.
4259 *
4260 * @subsection EXPRPARSE
4261 *
4262 * This callback is called when an expression is parsed from a string and an operator with the name of the expression handler is found.
4263 * The given string points to the beginning of the arguments of the expression, that is, the beginning of "..." in the string `myfunc(...)`.
4264 * The callback shall interpret "..." and create an expression, probably via `SCIPcreateExprMyfunc()`, and return this created expression
4265 * and the position of the last character in "..." to SCIP.
4266 * When creating an expression, the given `ownercreate` and `ownercreatedata` shall be passed on.
4267 *
4268 * The string "..." likely contains one or several other expressions that will be the children of the `myfunc` expression.
4269 * `SCIPparseExpr()` shall be used to parse these expressions.
4270 *
4271 * For an expression that takes only one argument and has no parameters, the parsing routine is straightforward.
4272 * For example:
4273 * @refsnippet{src/scip/expr_exp.c,SnippetExprParseExp}
4274 *
4275 * For an expression that has additional data, the parsing routine is slightly more complex.
4276 * For the signpower expression, this parses `signpower(<child>,<exponent>)`:
4277 * @refsnippet{src/scip/expr_pow.c,SnippetExprParseSignpower}
4278 *
4279 * If this callback is not implemented, the expression cannot be parsed.
4280 * For instance, `.cip` files with nonlinear constraints that use this expression cannot be read.
4281 *
4282 * @subsection EXPRCURVATURE
4283 *
4284 * This callback is called when an expression is checked for convexity or concavity.
4285 * It is important to note that the callback is given a desired curvature (convex, concave, or both (=linear))
4286 * and the callback is required to return whether the given expression has the desired curvature.
4287 * In addition, it can state conditions on the curvature of the children under which the desired curvature
4288 * can be achieved and it can take bounds on the children into account.
4289 * SCIPevalExprActivity() and SCIPexprGetActivity() shall be used to evaluate and get bounds on a child expression.
4290 *
4291 * The implementation in the absolute-value expression handler serves as an example:
4292 * @refsnippet{src/scip/expr_abs.c,SnippetExprCurvatureAbs}
4293 *
4294 * If this callback is not implemented, the expression is assumed to be indefinite.
4295 *
4296 * @subsection EXPRMONOTONICITY
4297 *
4298 * This callback is called when an expression is checked for its monotonicity with respect to a given child.
4299 * It is given the index of the child and shall return whether the expression is monotonically increasing or decreasing with respect to this child,
4300 * that is, when assuming that all other children are fixed.
4301 * Bounds on the children can be taken into account.
4302 * These can be evaluated and obtained via SCIPevalExprActivity() and SCIPexprGetActivity().
4303 *
4304 * The implementation in the absolute value expression handler serves as an example:
4305 * @refsnippet{src/scip/expr_abs.c,SnippetExprMonotonicityAbs}
4306 *
4307 * If this callback is not implemented, the expression is assumed to be not monotone in any child.
4308 *
4309 * @subsection EXPRINTEGRALITY
4310 *
4311 * This callback is called when an expression is checked for integrality, that is,
4312 * whether the expression evaluates always to an integral value in a feasible solution.
4313 * An implementation usually uses SCIPexprIsIntegral() to check whether children evaluate to an integral value.
4314 *
4315 * For example, a sum expression is returned to be integral if all coefficients and all children are integral:
4316 * @refsnippet{src/scip/expr_sum.c,SnippetExprIntegralitySum}
4317 *
4318 * If this callback is not implemented, the expression is assumed to be not integral.
4319 *
4320 * @subsection EXPRHASH
4321 *
4322 * This callback is called when a hash value is computed for an expression.
4323 * The hash is used to quickly identify expressions that may be equal (or better: to identify expressions that cannot be pairwise equal).
4324 *
4325 * The hash shall be unique to the expression as likely as positive.
4326 * To achieve this, the hashing algorithm shall use the expression type, expression data, and hash of children as input.
4327 * It must also be deterministic in this input.
4328 *
4329 * For example, for the sum expression, the coefficients and the hashes of all children are taken into account:
4330 * @refsnippet{src/scip/expr_sum.c,SnippetExprHashSum}
4331 *
4332 * `EXPRHDLR_HASHKEY` is a constant that is unique to the sum expression handler.
4333 *
4334 * If this callback is not implemented, a hash is computed from the expression handler name and the hashes of all children.
4335 *
4336 * @subsection EXPRCOMPARE
4337 *
4338 * This callback is called when two expressions (expr1 and expr2) that are handled by the expression handlers need to be compared.
4339 * The method shall impose an order on expressions and thus must return
4340 * - -1 if expr1 < expr2, or
4341 * - 0 if expr1 = expr2, or
4342 * - 1 if expr1 > expr2.
4343 *
4344 * The callback may use SCIPcompareExpr() to compare children of expr1 and expr2.
4345 *
4346 * For example, for pow expressions, the order is given by the order of the children.
4347 * If the children are equal, then the order of the exponents is used:
4348 * @refsnippet{src/scip/expr_pow.c,SnippetExprComparePow}
4349 *
4350 * If this callback is not implemented, a comparison is done based on the children of expr1 and expr2 only.
4351 * If the expression is stateful, it must implement this callback.
4352 *
4353 * @subsection EXPRBWDIFF
4354 *
4355 * This callback is called when the gradient or Hessian of a function that is represented by an expression is computed.
4356 *
4357 * The method shall compute the partial derivative of the expression w.r.t. a child with specified childidx.
4358 * That is, it should return
4359 * \f[
4360 * \frac{\partial \text{expr}}{\partial \text{child}_{\text{childidx}}}
4361 * \f]
4362 *
4363 * See also \ref SCIP_EXPR_DIFF "Differentiation methods in scip_expr.h" for more details on automatic differentiation of expressions.
4364 *
4365 * For the product expression, backward differentiation is implemented as follows:
4366 * @refsnippet{src/scip/expr_product.c,SnippetExprBwdiffProduct}
4367 *
4368 * If this callback is not implemented, gradients and Hessian of functions that involve this expression cannot be computed.
4369 * This can be hurtful for performance because linear relaxation routines that rely on gradient evaluation (e.g., nlhdlr_convex) cannot be used.
4370 *
4371 * @subsection EXPRFWDIFF
4372 *
4373 * This callback is called when the Hessian of a function that is represented by an expression is computed.
4374 * It may also be used to compute first derivatives.
4375 *
4376 * The method shall evaluate the directional derivative of the expression when interpreted as an operator
4377 * \f$ f(c_1, \ldots, c_n) \f$, where \f$ c_1, \ldots, c_n \f$ are the children.
4378 * The directional derivative is
4379 * \f[
4380 * \sum_{i = 1}^n \frac{\partial f}{\partial c_i} D_u c_i,
4381 * \f]
4382 * 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,
4383 * which can be accessed via SCIPexprGetDot().
4384 * The point at which to compute the derivative is given by SCIPexprGetEvalValue().
4385 *
4386 * See also \ref SCIP_EXPR_DIFF "Differentiation methods in scip_expr.h" for more details on automatic differentiation of expressions.
4387 *
4388 * 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$:
4389 * @refsnippet{src/scip/expr_product.c,SnippetExprFwdiffProduct}
4390 *
4391 * 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.
4392 *
4393 * @subsection EXPRBWFWDIFF
4394 *
4395 * This callback is called when the Hessian of a function that is represented by an expression is computed.
4396 *
4397 * The method computes the total derivative, w.r.t. its children, of the partial derivative of expr w.r.t. childidx.
4398 * Equivalently, it computes the partial derivative w.r.t. childidx of the total derivative.
4399 *
4400 * 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,
4401 * and the method should return
4402 * \f[
4403 * \sum_{i = 1}^n \frac{\partial^2 f}{\partial c_i} \partial c_{\text{childidx}} D_u c_i,
4404 * \f]
4405 * 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,
4406 * which can be accessed via SCIPexprGetDot().
4407 *
4408 * Thus, if \f$ n = 1 \f$ (i.e., the expression represents a univariate operator), the method should return
4409 * \f[
4410 * f^{\prime \prime}(\text{SCIPexprGetEvalValue}(c)) D_u c.
4411 * \f]
4412 *
4413 * See also \ref SCIP_EXPR_DIFF "Differentiation methods in scip_expr.h" for more details on automatic differentiation of expressions.
4414 *
4415 * For a product, \f$f(x) = c\prod_i x_i\f$, the directional derivative is
4416 * \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$:
4417 * @refsnippet{src/scip/expr_product.c,SnippetExprBwfwdiffProduct}
4418 *
4419 * If this callback is not implemented, there is currently no particular performance impact.
4420 * 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.
4421 *
4422 * @subsection EXPRINTEVAL
4423 *
4424 * This callback is called when bounds on an expression need to be computed.
4425 * 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.
4426 * The latter can be accessed via SCIPexprGetActivity().
4427 *
4428 * Often, interval evaluation is implemented analogous to evaluation with numbers.
4429 * For example, for products:
4430 * @refsnippet{src/scip/expr_product.c,SnippetExprIntevalProduct}
4431 *
4432 * 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.
4433 *
4434 * @subsection EXPRESTIMATE
4435 *
4436 * While \ref EXPRINTEVAL computes constant under- and overestimators,
4437 * this callback is called when linear under- or overestimators need to be computed.
4438 * The estimator shall be as tight as possible at a given point and must be valid w.r.t. given (local) bounds.
4439 * If the value of the estimator in the reference point is smaller (larger) than a given targetvalue
4440 * when underestimating (overestimating), then no estimator needs to be computed.
4441 * Note, that targetvalue can be infinite if any estimator will be accepted.
4442 *
4443 * The callback shall also indicate whether the estimator is also valid w.r.t. given global bounds and for which
4444 * child a reduction in the local bounds (usually by branching) would improve the estimator.
4445 *
4446 * For the absolute-value expression, the under- and overestimators are computed as follows:
4447 * @refsnippet{src/scip/expr_abs.c,SnippetExprEstimateAbs}
4448 *
4449 * 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.
4450 *
4451 * @subsection EXPRINITESTIMATES
4452 *
4453 * This callback is similar to \ref EXPRESTIMATE, but is not given a reference point.
4454 * It can also return several (up to \ref SCIP_EXPR_MAXINITESTIMATES many) estimators.
4455 * A usecase for this callback is the construction of an initial linear relaxation of nonlinear constraints.
4456 *
4457 * For the absolute-value expression, the following initial under- and overestimators are computed:
4458 * @refsnippet{src/scip/expr_abs.c,SnippetExprInitestimatesAbs}
4459 *
4460 * If this callback is not implemented, the initial linear relaxation for nonlinear constraints may be less tight.
4461 * This can have a minor effect on performance, as long as \ref EXPRESTIMATE has been implemented and the linear relaxation
4462 * is still bounded (e.g., when all nonlinear variables have finite bounds).
4463 *
4464 * @subsection EXPRSIMPLIFY
4465 *
4466 * This callback shall try to simplify an expression by applying algebraic transformations.
4467 * It shall return the simplified (and equivalent) expression.
4468 * It can assume that children have been simplified.
4469 * If no simplification is possible, then it can return the original expression, but needs to capture it.
4470 * When creating a new expression, it shall pass on the given ownerdata creation callback and its data.
4471 *
4472 * A simplification that should be implemented by every expression handler at the moment is constant-folding, i.e.,
4473 * returning a value-expression if every child is a value expression.
4474 * For an example, the simplification for the exponentiation expression is implemented as
4475 * @refsnippet{src/scip/expr_exp.c,SnippetExprSimplifyExp}
4476 *
4477 * See also SCIPsimplifyExpr() for more information on implemented simplification rules.
4478 *
4479 * 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.
4480 * (Also bugs may show up as this situation is untested.)
4481 *
4482 * @subsection EXPRREVERSEPROP
4483 *
4484 * This callback is called when given bounds on an expression shall be propagated over the children of an expression.
4485 * Already existing bounds on the children (see \ref EXPRINTEVAL) shall be used.
4486 * That is, the method shall compute an interval overestimate on
4487 * \f[
4488 * \{ x_i : f(c_1,\ldots,c_{i-1},x_i,c_{i+1},\ldots,c_n) \in \text{bounds} \}
4489 * \f]
4490 * for each child \f$i\f$, given bounds on f and initial intervals \f$c_i, i=1,\ldots,n,\f$, for the children.
4491 *
4492 * For univariate expressions, the implementation can be rather straightforward, e.g., for absolute value:
4493 * @refsnippet{src/scip/expr_abs.c,SnippetExprReversepropAbs}
4494 *
4495 * For multivariate expressions, it can be more complicated, e.g., for products:
4496 * @refsnippet{src/scip/expr_product.c,SnippetExprReversepropProduct}
4497 *
4498 * If this callback is not implemented, the performance of domain propagation for nonlinear constraints will be impacted severely.
4499 */
4500
4501/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4502
4503/**@page NLHDLR How to add nonlinear handlers
4504 *
4505 * Nonlinear handlers define the extended formulations of nonlinear constraints and provide domain propagation and separation routines on this extended formulation.
4506 * In difference to \ref EXPRHDLR "expression handlers", they do not define a function, but instead identify a
4507 * 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.
4508 * The structure typically consists of a composition of expressions.
4509 *
4510 * Nonlinear handlers are a new plugin type in SCIP and may still have some rough edges.
4511 * They resemble constraint handlers in some sense, but are specific to the handling of nonlinear constraints.
4512 * We suggest to read section "New Handler for Nonlinear Constraints" in the SCIP 8.0 release report (2021)
4513 * to understand the role and use of nonlinear handlers before attempting to implement one.
4514 *
4515 * A complete list of all nonlinear handlers contained in this release can be found \ref NLHDLRS "here".
4516 * 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.
4517 *
4518 * Here is what you have to do to implement a nonlinear handler:
4519 * -# 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
4520 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
4521 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
4522 * -# Use `SCIPincludeNlhdlrMystruct()` in order to include the nonlinear handler into your SCIP instance, e.g., in the main file of your project. \n
4523 If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
4524 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mystruct".
4525 * -# Adjust the properties of the nonlinear handler (see \ref NLHDLR_PROPERTIES).
4526 * -# Define the nonlinear handler data and nonlinear handler expression data (see \ref NLHDLR_DATA). This is optional.
4527 * -# Implement the interface methods (see \ref NLHDLR_INTERFACE).
4528 * -# Implement the fundamental callback methods (see \ref NLHDLR_FUNDAMENTALCALLBACKS).
4529 * -# Implement the additional callback methods (see \ref NLHDLR_ADDITIONALCALLBACKS), where necessary.
4530 *
4531 * Additional documentation for the callback methods of a nonlinear handler, in particular for the input parameters,
4532 * can be found in the file \ref type_nlhdlr.h.
4533 *
4534 * @section NLHDLR_PROPERTIES Properties of a Nonlinear Handler
4535 *
4536 * At the top of the new file `nlhdlr_mystruct.c`, you can find the nonlinear handler properties.
4537 * These are given as compiler defines.
4538 * The properties you have to set have the following meaning:
4539 *
4540 * \par NLHDLR_NAME: the name of the nonlinear handler.
4541 * This name is used in the interactive shell to address the nonlinear handler.
4542 * Additionally, if you are searching for a nonlinear handler with SCIPfindNlhdlrNonlinear(), this name is looked up.
4543 * Names have to be unique: no two nonlinear handlers may have the same name.
4544 *
4545 * \par NLHDLR_DESC: the description of the nonlinear handler.
4546 * This string is printed as a description of the nonlinear handler in the interactive shell.
4547 *
4548 * \par NLHDLR_DETECTPRIORITY: the priority of the nonlinear handler when detecting structure.
4549 * This priority decides when the \ref NLHDLRDETECT callback of the nonlinear handler is called, relative to other nonlinear handlers, on an expression.
4550 * Typically, the priority should be strictly positive.
4551 * 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.
4552 *
4553 * \par NLHDLR_ENFOPRIORITY: the priority of the nonlinear handler when enforcing constraints in the extended formulations.
4554 * 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.
4555 * A high priority means that the nonlinear handler will be called before others.
4556 * The nonlinear handler "default" has enforcement priority 0.
4557 *
4558 * @section NLHDLR_DATA Nonlinear Handler Data and Nonlinear Handler Expression Data
4559 *
4560 * Below the header "Data structures" you can find structs called `struct SCIP_NlhdlrData` and `struct SCIP_NlhdlrExprData`.
4561 * In this first data structure, you can store the data of your nonlinear handler.
4562 * For example, you should store the adjustable parameters of the nonlinear handler in this data structure.
4563 * In the second data structure, you can store data that is unique to an expression for which the nonlinear handler detected a structure.
4564 * For example, the nonlinear handler for quotients stores a representation of a detected quotient in this data structure.
4565 * \n
4566 * Defining nonlinear handler data and nonlinear handler expression data is optional. You can leave these structs empty.
4567 *
4568 * @section NLHDLR_INTERFACE Interface Methods
4569 *
4570 * At the bottom of `nlhdlr_mystruct.c`, you can find the interface method `SCIPincludeNlhdlrXyz()`,
4571 * which also appears in `nlhdlr_mystruct.h`.
4572 * `SCIPincludeNlhdlrXyz()` is called by the user, if (s)he wants to include the nonlinear handler,
4573 * i.e., if (s)he wants to use the nonlinear handler in his/her application.
4574 *
4575 * This method is responsible for notifying SCIP of the presence of the nonlinear handler.
4576 * For this, you must call SCIPincludeNlhdlrNonlinear() from SCIPincludeNlhdlrMystruct().
4577 * The function only expects the properties and fundamental callbacks of the nonlinear handler as arguments.
4578 * \ref NLHDLR_ADDITIONALCALLBACKS "Additional callbacks" must be added via setter functions as, e.g., SCIPnlhdlrSetCopyHdlr().
4579 *
4580 * If you are using nonlinear handler data, you have to allocate the memory for the data at this point and initialize it.
4581 * For freeing the nonlinear handler data, see \ref NLHDLRFREEHDLRDATA.
4582 * You may also add user parameters or statistic tables for your nonlinear handler, see \ref PARAM for how to add user parameters.
4583 *
4584 * For the bilinear nonlinear handler, the include method is as follows:
4585 * @refsnippet{src/scip/nlhdlr_bilinear.c,SnippetIncludeNlhdlrBilinear}
4586 *
4587 *
4588 * @section NLHDLR_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Nonlinear Handler
4589 *
4590 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
4591 * an operational algorithm.
4592 * They are passed to SCIP when the nonlinear handler is created and included in SCIP via SCIPincludeNlhdlrNonlinear(),
4593 * see @ref NLHDLR_INTERFACE.
4594 *
4595 * Nonlinear handlers have two fundamental callbacks that need to be implemented.
4596 * Additional documentation for the callback methods, in particular to their input parameters,
4597 * can be found in \ref type_nlhdlr.h.
4598 *
4599 * @subsection NLHDLRDETECT
4600 *
4601 * This callback is called by the handler for nonlinear constraints when extended formulations are constructed.
4602 * The result of this callback determines the extended formulation.
4603 *
4604 * The nonlinear handler shall analyze the given expression (`expr`) and decide whether it wants to contribute
4605 * in enforcing the relation between bounds or an auxiliary variable (`auxvar`) associated with this expression and
4606 * its descendants (e.g., children) via linear under- or overestimation, cut generation, and/or activity computation and propagation.
4607 * For linear under- or overestimation and cut generation, an auxiliary variable can be assumed to
4608 * be associated with the expression and auxiliary variables may be requested for descendant expressions.
4609 *
4610 * We distinguish the following enforcement methods:
4611 * - \ref SCIP_NLHDLR_METHOD_SEPABELOW : linear underestimation of `expr` or cut generation for the relation `expr` &le; `auxvar` (denoted as "below")
4612 * - \ref SCIP_NLHDLR_METHOD_SEPAABOVE : linear overestimation of `expr` or cut generation for the relation `expr` &ge; `auxvar` (denoted as "above")
4613 * - \ref SCIP_NLHDLR_METHOD_ACTIVITY : domain propagation (i.e., constant under/overestimation) for `expr`.
4614 *
4615 * On input, parameter `enforcing` indicates for any of these methods, whether
4616 * - 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,
4617 * or because analysis of the expression has shown that a relation like `expr` &ge; `auxvar` is not necessary to be satisfied,
4618 * - or there already exists a nonlinear handler that will provide this method in an "enforcement" sense, that is,
4619 * 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
4620 * it should still reach out to the expression handler or whether it would be dominated by some nonlinear handler.)
4621 *
4622 * The DETECT callback shall augment the `enforcing` bitmask by setting the enforcement methods it wants to provide in an "enforcement" sense.
4623 *
4624 * Additionally, the `participating` bitmask shall be set if the nonlinear handler wants to be called on this expression at all.
4625 * Here, it shall set all methods that it wants to provide, which are those set in `enforcing`, but additionally those where it wants
4626 * to participate but leave enforcement to another nonlinear handler.
4627 * This can be useful for nonlinear handlers that do not implement a complete enforcement, e.g., a handler that only contributes
4628 * cutting planes in some situations only.
4629 *
4630 * A nonlinear handler will be called only for those callbacks that it mentioned in `participating`, which is
4631 * - \ref NLHDLRENFO and/or \ref NLHDLRESTIMATE will be called with `overestimate==FALSE` if \ref SCIP_NLHDLR_METHOD_SEPABELOW has been set
4632 * - \ref NLHDLRENFO and/or \ref NLHDLRESTIMATE will be called with `overestimate==TRUE` if \ref SCIP_NLHDLR_METHOD_SEPAABOVE has been set
4633 * - \ref NLHDLRINTEVAL and/or \ref NLHDLRREVERSEPROP will be called if \ref SCIP_NLHDLR_METHOD_ACTIVITY has been set
4634 *
4635 * If \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE has been set, then at least one of the
4636 * callbacks \ref NLHDLRENFO and \ref NLHDLRESTIMATE needs to be implemented.
4637 * Also \ref NLHDLREVALAUX will be called in this case.
4638 * If \ref SCIP_NLHDLR_METHOD_ACTIVITY has been set, then at least one of \ref NLHDLRINTEVAL and \ref NLHDLRREVERSEPROP needs to be implemented.
4639 * If the nonlinear handler chooses not to participate, then it must not set `nlhdlrexprdata` and can leave `participating` at its
4640 * initial value (\ref SCIP_NLHDLR_METHOD_NONE).
4641 *
4642 * Additionally, a nonlinear handler that decides to participate in any of the enforcement methods must call
4643 * @ref SCIPregisterExprUsageNonlinear() for every subexpression that it will use and indicate whether
4644 * - it will use an auxiliary variable in \ref NLHDLRENFO or \ref NLHDLRESTIMATE,
4645 * - it will use activity for some subexpressions when computing estimators or cuts, and
4646 * - it will use activity for some subexpressions when in \ref NLHDLRINTEVAL or \ref NLHDLRREVERSEPROP.
4647 *
4648 * Note that auxiliary variables do not exist in subexpressions during DETECT and are not created by a call to @ref SCIPregisterExprUsageNonlinear().
4649 * They will be available when the \ref NLHDLRINITSEPA callback is called.
4650 *
4651 * For an example, see the implementation of the DETECT callback for the nonlinear handler for quotients (src/scip/nlhdlr_quotient.c).
4652 *
4653 * @subsection NLHDLREVALAUX
4654 *
4655 * This callback is called by the constraint handler for nonlinear constraints when the violation of constraints in the extended formulation
4656 * (`expr` &le;/&ge; `auxvar`) needs to be evaluated.
4657 * During constraint enforcement, this violation value is used to decide whether estimation and separation callbacks should be called.
4658 *
4659 * The method shall evaluate the expression w.r.t. the auxiliary variables that were introduced by the nonlinear handler (if any).
4660 * It can be assumed that the expression itself has been evaluated in the given sol.
4661 *
4662 * For an example, see the evaluation for the quotient nonlinear handler:
4663 * @refsnippet{src/scip/nlhdlr_quotient.c,SnippetNlhdlrEvalauxQuotient}
4664*
4665 * @section NLHDLR_ADDITIONALCALLBACKS Additional Callback Methods of a Nonlinear Handler
4666 *
4667 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
4668 * implemented for most applications, they can be used, for example, to initialize and free private data.
4669 * Additional callbacks can be passed via specific
4670 * <b>setter functions</b> after a call of SCIPincludeNlhdlrNonlinear(), see also @ref NLHDLR_INTERFACE.
4671 *
4672 * @subsection NLHDLRCOPYHDLR
4673 *
4674 * This callback is called when doing a copy of the constraint handler for nonlinear constraints.
4675 * It shall include the nonlinear handler into the copy of the constraint handler.
4676 *
4677 * @subsection NLHDLRFREEHDLRDATA
4678 *
4679 * If you are using nonlinear handler data (see \ref NLHDLR_DATA and \ref NLHDLR_INTERFACE), you have to implement this method
4680 * in order to free the nonlinear handler data.
4681 *
4682 * @subsection NLHDLRFREEEXPRDATA
4683 *
4684 * If you are using nonlinear handler expression data (see \ref NLHDLR_DATA and \ref NLHDLRDETECT), you have to implement this method
4685 * in order to free the nonlinear handler expression data.
4686 * This method is called when an extended formulation is freed.
4687 *
4688 * @subsection NLHDLRINIT
4689 *
4690 * This callback is called when the constraint handler for nonlinear constraints is initialized, that is, after the problem was transformed.
4691 * The nonlinear handler can use this callback to initialize or reset some data for the upcoming solve.
4692 *
4693 * @subsection NLHDLREXIT
4694 *
4695 * This callback is called when the constraint handler for nonlinear constraints is deinitialized, that is, before the transformed problem is freed.
4696 * The nonlinear handler can use this callback to free some data that was used for the previous solve only.
4697 *
4698 * @subsection NLHDLRINTEVAL
4699 *
4700 * This callback is called when bounds on a given expression shall be computed.
4701 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_ACTIVITY in \ref NLHDLRDETECT.
4702 * The method is given the currently available bounds to the expression and can return possibly tighter bounds.
4703 *
4704 * For a univariate quotient ((ax+b)/(cx+d)), the interval evaluation is implemented as follows:
4705 * @refsnippet{src/scip/nlhdlr_quotient.c,SnippetNlhdlrIntevalQuotient}
4706 *
4707 * @subsection NLHDLRREVERSEPROP
4708 *
4709 * This callback is called when bounds on a given expression shall be propagated to its successors.
4710 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_ACTIVITY in \ref NLHDLRDETECT.
4711 * The tighter intervals should be passed to the corresponding expression via SCIPtightenExprIntervalNonlinear().
4712 *
4713 * For a univariate quotient ((ax+b)/(cx+d)), reverse propagation is implemented as follows:
4714 * @refsnippet{src/scip/nlhdlr_quotient.c,SnippetNlhdlrReversepropQuotient}
4715 *
4716 * @subsection NLHDLRINITSEPA
4717 *
4718 * This callback is called when the constraint handler for nonlinear constraints initializes the LP relaxation (@ref CONSINITLP).
4719 * 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.
4720 * The method shall initialize the separation data of the nonlinear handler, if any, and add initial cuts to the LP relaxation.
4721 * It can assume that auxiliary variables are available for expressions for which auxiliary variables were requested via SCIPregisterExprUsageNonlinear() in \ref NLHDLRDETECT.
4722 *
4723 * @subsection NLHDLREXITSEPA
4724 *
4725 * This callback is called when the solving process is finished and the branch and bound process data is freed (@ref CONSEXITSOL).
4726 * 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.
4727 * The method shall deinitialize the separation data of the nonlinear handler, if any.
4728 *
4729 * @subsection NLHDLRENFO
4730 *
4731 * This callback is called when the constraint handler requires that the relation between the given expression and its auxiliary variable
4732 * (`expr` &le; `auxvar` or `expr` &ge; `auxvar`) is violated by a given solution and this solution needs to be separated.
4733 * 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.
4734 *
4735 * The nonlinear handler can enforce `expr` &le;/&ge; `auxvar` by
4736 * - separation, i.e., finding an affine hyperplane (a cut) that separates the given point, or
4737 * - bound tightening, i.e., changing bounds on a variable so that the given point is outside the updated domain, or
4738 * - adding branching scores to potentially split the current problem into two subproblems.
4739 *
4740 * If parameter `inenforcement` is FALSE, then only the first option (separation) is allowed.
4741 *
4742 * If the nonlinear handler always separates by computing a linear under- or overestimator of `expr`,
4743 * then it is usually easier to implement the \ref NLHDLRESTIMATE callback instead.
4744 *
4745 * Note, that the nonlinear handler may also choose to separate for a relaxation of the mentioned sets,
4746 * e.g., `expr` &le; upperbound(`auxvar`) or `expr` &ge; lowerbound(`auxvar`).
4747 * This is especially useful in situations where `expr` is the root expression of a constraint
4748 * and it is sufficient to satisfy `lhs` &le; `expr` &le; `rhs`.
4749 * The constraint handler ensures that `lhs` &le; lowerbound(`auxvar`) and upperbound(`auxvar`) &le; `rhs`.
4750 *
4751 * The constraint handler may call this callback first with `allowweakcuts` = FALSE and repeat later with
4752 * `allowweakcuts` = TRUE, if it didn't succeed to enforce a solution without using weak cuts.
4753 * If in enforcement and the nonlinear handler cannot enforce by separation or bound tightening, it should register
4754 * branching scores for those expressions where branching may help to compute tighter cuts in children.
4755 *
4756 * The nonlinear handler must set `result` to \ref SCIP_SEPARATED if it added a cut,
4757 * to \ref SCIP_REDUCEDDOM if it added a bound change, and
4758 * to \ref SCIP_BRANCHED if it added branching scores.
4759 * Otherwise, it may set result to \ref SCIP_DIDNOTRUN or \ref SCIP_DIDNOTFIND.
4760 *
4761 * @subsection NLHDLRESTIMATE
4762 *
4763 * This callback is called when the constraint handler requires that the relaxation between the given expression and its auxiliary variable
4764 * (`expr` &le; `auxvar` or `expr` &ge; `auxvar`) is violated by a given solution and this solution needs to be separated.
4765 * 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.
4766 * This method is a simpler alternative to \ref NLHDLRENFO and is called if \ref NLHDLRENFO is not implemented or does not succeed.
4767 *
4768 * The method shall compute one or several linear under- or overestimator of `expr` that are as tight as possible at a given point.
4769 * If the value of the estimator in the solution is smaller (larger) than a given targetvalue
4770 * when underestimating (overestimating), then no estimator needs to be computed.
4771 * Note, that targetvalue can be infinite if any estimator will be accepted.
4772 * If successful, it shall store the estimators in the given `rowpreps` data structure and set the
4773 * `rowprep->local` flag accordingly (SCIProwprepSetLocal()).
4774 * The sidetype of a rowprep must be set to \ref SCIP_SIDETYPE_LEFT if overestimating and
4775 * \ref SCIP_SIDETYPE_RIGHT if underestimating.
4776 *
4777 * The callback may also be required to indicate for which expression a reduction in the local bounds (usually by branching) would improve the estimator.
4778 * This is done by a call to SCIPaddExprsViolScoreNonlinear().
4779 *
4780 * For the quotient nonlinear handler, the estimators are computed as follows:
4781 * @refsnippet{src/scip/nlhdlr_quotient.c,SnippetNlhdlrEstimateQuotient}
4782 */
4783
4784/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4785
4786/**@page DIVINGHEUR How to implement a diving heuristic
4787 *
4788 * Diving heuristics are an important addon to the branch-and-cut search. A diving heuristic explores a single probing
4789 * path down the search tree. In contrast to the regular search guided by branching rule(s) and the selected
4790 * node selector, the diving is performed in an auxiliary tree originating from the focus node of the main
4791 * search tree where the heuristic was called. The advantage of this approach is that many different scoring mechanisms
4792 * can be safely tried as diving heuristic and may probably lead to better solutions. SCIP has a lot of diving heuristics
4793 * included in its default plugin set.
4794 * \n
4795 *
4796 * Since SCIP version 3.2, the diving heuristics have been redesigned to contain mainly the scoring function used by the
4797 * heuristic. In order to implement a user-defined diving heuristic, it is possible to create one (or several)
4798 * divesets that control the scoring mechanism and add them to the primal heuristic. This has the advantage that
4799 * less code is necessary to create a working diving heuristic. The SCIP statistics now also display some interesting statistics
4800 * about every diveset together in the section 'Diving Statistics'.
4801 * \n
4802 *
4803 * This page contains the necessary steps to understand and include a diveset into ones primal diving heuristic plugin. As
4804 * a prerequisite, you should understand the basic implementation steps for a primal heuristic, see \ref HEUR.
4805 * In order to make use of divesets, they must be included _after_ the primal heuristic to which they should belong
4806 * has been included, by using SCIPincludeDiveset(). This will create the data structure for the diveset and
4807 * append it to the list of divesets belonging to the heuristic, which can be retrieved later together with their number
4808 * by using SCIPheurGetDivesets() and SCIPheurGetNDivesets(), respectively. No further memory allocation or deletion is needed;
4809 * As a member of the heuristic, SCIP automatically takes care of freeing the diveset when it is exiting.
4810 * \n
4811 *
4812 * Before the inclusion, one may think of adjusting the various properties that a diveset offers to control
4813 * the behavior of the algorithm. These are subject to the following section.
4814 * \n
4815 *
4816 * It is mandatory to implement the fundamental scoring callback of the diveset, which is explained in more detail
4817 * in Section \ref DIVING_FUNDAMENTALCALLBACKS.
4818 * \n
4819 *
4820 * Once the properties have been carefully adjusted and the scoring
4821 * has been defined, use the method SCIPperformGenericDivingAlgorithm() inside the execution callback (\ref HEUREXEC) of the primal
4822 * heuristic to which the diveset belongs, after checking possible preliminaries that may not be met at all times of the search.
4823 * \n
4824 *
4825 * For a code example, we refer to \ref heur_guideddiving.h, which guides the diving into the direction of the current incumbent solution.
4826 * Before it calls SCIPperformGenericDivingAlgorithm(), it checks whether an incumbent is available, and returns if there is none.
4827 *
4828 *
4829 * @section DIVING_PARAMETERS User parameters and properties for every diveset
4830 *
4831 * Every diveset controls the diving behavior through a set of user-defined parameters, which are explained in the following:
4832 *
4833 * \par MINRELDEPTH
4834 * the minimal relative depth (to the maximum depth explored during regular search) of the current focus node to start diving
4835 *
4836 * \par MAXRELDEPTH
4837 * the maximal relative depth (to the maximum depth explored during regular search) of the current focus node to start diving
4838 *
4839 * \par MAXLPITERQUOT
4840 * maximal fraction of diving LP iterations compared to node LP iterations that this dive controller may consume
4841 *
4842 * \par MAXLPITEROFS
4843 * an additional number of allowed LP iterations
4844 *
4845 * \par MAXDIVEUBQUOT
4846 * maximal quotient (curlowerbound - lowerbound)/(cutoffbound - lowerbound)
4847 * where diving is performed (0.0: no limit)
4848 *
4849 * \par MAXDIVEAVGQUOT
4850 * maximal quotient (curlowerbound - lowerbound)/(avglowerbound - lowerbound)
4851 * where diving is performed (0.0: no limit)
4852 *
4853 * \par MAXDIVEUBQUOTNOSOL
4854 * maximal UBQUOT when no solution was found yet (0.0: no limit)
4855 *
4856 * \par MAXDIVEAVGQUOTNOSOL
4857 * maximal AVGQUOT when no solution was found yet (0.0: no limit)
4858 *
4859 * \par BACKTRACK
4860 * use one level of backtracking if infeasibility is encountered?
4861 *
4862 * \par LPRESOLVEDOMCHGQUOT
4863 * parameter to control LP resolve dynamically based on this percentage of observed bound changes relative to all variables or
4864 * the LP branching candidates (integer variables with fractional solution values) from the last node where an LP has been solved.
4865 * This property has no effect when the LPSOLVEFREQ is set to 1.
4866 *
4867 * \par LPSOLVEFREQ
4868 * 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
4869 * diveset to solve _all_ intermediate LPs) or 0 to only resolve the LP relaxation after propagation found at least a certain percentage
4870 * domain changes, see also the previous LPRESOLVEDOMCHGQUOT parameter.
4871 *
4872 * \par ONLYLPBRANCHCANDS
4873 * Set this property to TRUE if only LP branching candidates be considered for the execution of the diving algorithm instead of the slower but
4874 * more general constraint handler diving variable selection.
4875 *
4876 * \par DIVETYPES
4877 * bit mask that represents all supported dive types. Irrelevant if only LP branching candidates should be scored, otherwise, different
4878 * constraint handlers may ask the diveset if it supports their preferred divetype. See \ref type_heur.h for a list of
4879 * available dive types.
4880 *
4881 * @section DIVING_FUNDAMENTALCALLBACKS Fundamental callbacks of a diveset
4882 *
4883 * Only one callback is necessary to complete a diveset to guide the diving search performed:
4884 *
4885 * @subsection DIVESETGETSCORE
4886 *
4887 * The scoring callback expects a candidate variable and calculates a score value and a preferred direction. The selected
4888 * variable for diving will be one that _maximizes_ the score function provided by the diveset.
4889 * If the diveset should support more than one possible type of diving, it may use the divetype argument as a hint how
4890 * the caller of the score function (could be the diving algorithm itself or one of the constraint handlers that
4891 * implement diving variable selection) intends to perform the search.
4892 *
4893 * @section DIVING_FURTHERINFO Further information
4894 *
4895 * This is all there is to extend the SCIP set of diving heuristics by a new one. For further information, please see
4896 * diveset related methods in \ref type_heur.h, \ref pub_heur.h, \ref heuristics.h, and \ref heur_guideddiving.h or
4897 * other diving heuristics that implement diving through a diveset.
4898 */
4899
4900/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4901
4902/**@page RELAX How to add relaxation handlers
4903 *
4904 * SCIP provides specific support for LP relaxations of constraint integer programs. In addition, relaxation handlers,
4905 * also called relaxators, can be used to include other relaxations, e.g. Lagrange relaxations or semidefinite
4906 * relaxations. The relaxation handler manages the necessary data structures and calls the relaxation solver to generate dual
4907 * bounds and primal solution candidates.
4908 * \n
4909 * However, the data to define a single relaxation must either be extracted by the relaxation handler itself (e.g., from
4910 * the user defined problem data, the LP information, or the integrality conditions), or it must be provided by the constraint
4911 * handlers. In the latter case, the constraint handlers have to be extended to support this specific relaxation.
4912 * \n
4913 *
4914 * We now explain how users can add their own relaxation handlers using the C interface. As an example, look into the NLP
4915 * relaxation handler of the \ref RELAXATOR_MAIN "Relaxator example" (examples/Relaxator/src/relax_nlp.c). It is very easy to
4916 * transfer the C explanation to C++: whenever a method should be implemented using the SCIP_DECL_RELAX... notion,
4917 * reimplement the corresponding virtual member function of the abstract scip::ObjRelax wrapper base class.
4918 *
4919 * Additional documentation for the callback methods of a relaxation handler can be found in the file type_relax.h.
4920 *
4921 * Here is what you have to do to implement a relaxation handler:
4922 * -# Copy the template files src/scip/relax_xyz.c and src/scip/relax_xyz.h into files named "relax_myrelaxator.c"
4923 * and "relax_myrelaxator.h".
4924 * \n
4925 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
4926 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
4927 * -# Use `SCIPincludeRelaxMyrelaxator()` in order to include the relaxation handler into your SCIP instance,
4928 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
4929 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
4930 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myrelaxator".
4931 * -# Adjust the properties of the relaxation handler (see \ref RELAX_PROPERTIES).
4932 * -# Define the relaxation handler data (see \ref RELAX_DATA). This is optional.
4933 * -# Implement the interface methods (see \ref RELAX_INTERFACE).
4934 * -# Implement the fundamental callback methods (see \ref RELAX_FUNDAMENTALCALLBACKS).
4935 * -# Implement the additional callback methods (see \ref RELAX_ADDITIONALCALLBACKS). This is optional.
4936 *
4937 *
4938 * @section RELAX_PROPERTIES Properties of a Relaxation Handler
4939 *
4940 * At the top of the new file "relax_myrelaxator.c" you can find the relaxation handler properties,
4941 * which are given as compiler defines.
4942 * In the C++ wrapper class, you have to provide the relaxation handler properties by calling the constructor
4943 * of the abstract base class scip::ObjRelax from within your constructor.
4944 * The properties have the following meaning:
4945 *
4946 * \par RELAX_NAME: the name of the relaxation handler.
4947 * This name is used in the interactive shell to address the relaxation handler.
4948 * Additionally, if you are searching for a relaxation handler with SCIPfindRelax(), this name is looked up.
4949 * Names have to be unique: no two relaxation handlers may have the same name.
4950 *
4951 * \par RELAX_DESC: the description of the relaxation handler.
4952 * This string is printed as a description of the relaxation handler in the interactive shell.
4953 *
4954 * \par RELAX_PRIORITY: the priority of the relaxation handler.
4955 * During each relaxation solving round, the included relaxation handlers and the
4956 * price-and-cut loop for solving the LP relaxation are called in a predefined order, which is given by the priorities
4957 * of the relaxation handlers.
4958 * First, the relaxation handlers with non-negative priority are called in the order of decreasing priority.
4959 * Next, the price-and-cut loop for solving the LP relaxation is executed.
4960 * Finally, the relaxation handlers with negative priority are called in the order of decreasing priority.
4961 * \n
4962 * Usually, you will have only one relaxation handler in your application and thus only have to decide whether it should
4963 * be called before or after solving the LP relaxation. For this decision you should consider the complexity of
4964 * the relaxation solving algorithm and the impact of the resulting solution: if your relaxation handler provides a fast
4965 * algorithm that usually has a high impact (i.e. the relaxation is a good approximation of the
4966 * feasible region of the subproblem and the solution severely improves the dual bound), it should have a non-negative
4967 * priority.
4968 * \n
4969 * Note that for certain applications, it is useful to disable the LP relaxation and only use your custom relaxation.
4970 * This can easily be achieved by setting the "lp/solvefreq" parameter to -1.
4971 *
4972 * \par RELAX_FREQ: the default frequency for solving the relaxation.
4973 * The frequency defines the depth levels at which the relaxation solving method \ref RELAXEXEC is called.
4974 * For example, a frequency of 7 means, that the relaxation solving callback is executed for subproblems that are in depth
4975 * 0, 7, 14, ... of the branching tree. A frequency of 0 means that the callback is only executed at the root node, i.e.,
4976 * only the relaxation of the root problem is solved. A frequency of -1 disables the relaxation handler.
4977 *
4978 *
4979 *
4980 * @section RELAX_DATA Relaxation Handler Data
4981 *
4982 * Below the header "Data structures" you can find a struct which is called "struct SCIP_RelaxData".
4983 * In this data structure, you can store the data of your relaxation handler. For example, you should store the adjustable
4984 * parameters of the relaxation handler in this data structure.
4985 * If you are using C++, you can add relaxation handler data as usual as object variables to your class.
4986 * \n
4987 * Defining relaxation handler data is optional. You can leave the struct empty.
4988 *
4989 *
4990 * @section RELAX_INTERFACE Interface Methods
4991 *
4992 * At the bottom of "relax_myrelaxator.c", you can find the interface method SCIPincludeRelaxMyrelaxator(),
4993 * which also appears in "relax_myrelaxator.h".
4994 * SCIPincludeRelaxMyrelaxator() is called by the user, if (s)he wants to include the relaxation handler,
4995 * i.e., if (s)he wants to use the relaxation handler in his/her application.
4996 *
4997 * This method only has to be adjusted slightly.
4998 * It is responsible for notifying SCIP of the presence of the relaxation handler. For this, you can either call
4999 * SCIPincludeRelax(),
5000 * or SCIPincludeRelaxBasic() since SCIP version 3.0. In the latter variant, \ref RELAX_ADDITIONALCALLBACKS "additional callbacks"
5001 * must be added via setter functions as, e.g., SCIPsetRelaxCopy(). We recommend this latter variant because
5002 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
5003 * variant must be manually adjusted with every SCIP release containing new callbacks for relaxation handlers in order to compile.
5004 *
5005 * If you are using relaxation handler data, you have to allocate the memory for the data at this point.
5006 * You can do this by calling:
5007 * \code
5008 * SCIP_CALL( SCIPallocBlockMemory(scip, &relaxdata) );
5009 * \endcode
5010 * You also have to initialize the fields in struct SCIP_RelaxData afterwards.
5011 *
5012 * You may also add user parameters for your relaxation handler, see the method SCIPincludeConshdlrKnapsack() in
5013 * the \ref cons_knapsack.h "knapsack constraint handler" for an example of how to add user parameters.
5014 *
5015 *
5016 * @section RELAX_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Relaxation Handler
5017 *
5018 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
5019 * an operational algorithm.
5020 * They are passed together with the relaxation handler itself to SCIP using SCIPincludeRelax() or SCIPincludeRelaxBasic(),
5021 * see @ref RELAX_INTERFACE.
5022 *
5023 *
5024 * Relaxation handler plugins have only one fundamental callback method, namely the \ref RELAXEXEC method.
5025 * This method has to be implemented for every relaxation handler; the other callback methods are optional.
5026 * In the C++ wrapper class scip::ObjRelax, the scip_exec() method (which corresponds to the \ref RELAXEXEC callback) is a virtual
5027 * abstract member function.
5028 * You have to implement it in order to be able to construct an object of your relaxation handler class.
5029 *
5030 * Additional documentation for the callback methods can be found in type_relax.h.
5031 *
5032 * @subsection RELAXEXEC
5033 * The RELAXEXEC is called in each relaxation solving round. It should solve the current
5034 * subproblem's relaxation.
5035 *
5036 * Note that, like the LP relaxation, the relaxation handler should only operate on variables for which the corresponding
5037 * column exists in the transformed problem. Typical methods called by a relaxation handler are SCIPconstructLP() and SCIPflushLP() to
5038 * make sure that the LP of the current node is constructed and its data can be accessed via calls to SCIPgetLPRowsData()
5039 * and SCIPgetLPColsData(), and SCIPseparateSol() to call the cutting plane separators for a given primal solution.
5040 *
5041 * The lowerbound computed by the relaxation should be returned in the lowerbound pointer. If the relaxation improves on the best
5042 * relaxation already computed (either <code>SCIPisRelaxSolValid()</code> returns FALSE, meaning that no relaxation solution
5043 * is available so far, or the lowerbound is larger than the value returned by <code>SCIPgetRelaxSolObj()</code>), then the primal
5044 * solution of the relaxation should be stored inside the data structures of SCIP with <code>SCIPsetRelaxSolVal()</code>,
5045 * <code>SCIPsetRelaxSolVals()</code> or <code>SCIPsetRelaxSolValsSol()</code>. If you set the values one by one, you will need to call
5046 * <code>SCIPmarkRelaxSolValid()</code> to inform SCIP that the solution is complete and valid. With the "includeslp" argument of
5047 * <code>SCIPsetRelaxSolVals()</code>, <code>SCIPsetRelaxSolValsSol()</code> and <code>SCIPmarkRelaxSolValid()</code> you need to tell SCIP
5048 * 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
5049 * lowerbound of this relaxator is larger than the LP's. You may also call SCIPtrySolFree() directly from the
5050 * relaxation handler to make sure that a solution is added to the solution storage if it is feasible, even if the relaxator does not
5051 * include the LP or another relaxator produced a stronger bound. Also note that when setting the values of the relaxation solution one by one,
5052 * the objective value of the relaxation solution will be updated incrementally. If the whole solution should be updated, using SCIPsetRelaxSolVals()
5053 * instead or calling SCIPclearRelaxSolVals() before setting the first value to reset the solution and the objective value to 0 may help the numerics.
5054 * Furthermore, there is a list of external branching candidates, that can be filled by relaxation handlers and constraint handlers,
5055 * allowing branching rules to take these candidates as a guide on how to split the problem into subproblems. If the relaxation
5056 * solution is enforced, the integrality constraint handler will add external branching candidates for the relaxation solution
5057 * automatically, but the relaxation handler can also directly call <code>SCIPaddExternBranchCand()</code>.
5058 *
5059 * Usually, the RELAXEXEC callback only solves the relaxation and provides a lower (dual) bound through the corresponding pointer and
5060 * possibly a solution through <code>SCIPsetRelaxSolVal()</code> calls.
5061 * However, it may also produce domain reductions, add additional constraints or generate cutting planes. It has the
5062 * following options:
5063 * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
5064 * - adding an additional constraint and stating that the relaxation handler should not be called again on the same
5065 * relaxation (result SCIP_CONSADDED)
5066 * - reducing a variable's domain and stating that the relaxation handler should not be called again on the same
5067 * relaxation (result SCIP_REDUCEDDOM)
5068 * - adding a cutting plane to the LP and stating that the relaxation handler should not be called again on the same
5069 * relaxation (result SCIP_SEPARATED)
5070 * - stating that the relaxation handler solved the relaxation and should not be called again on the same relaxation
5071 * (result SCIP_SUCCESS)
5072 * - interrupting the solving process to wait for additional input, e.g., cutting planes (result SCIP_SUSPENDED)
5073 * - stating that the separator was skipped (result SCIP_DIDNOTRUN).
5074 *
5075 * In the above criteria, "the same relaxation" means that the LP relaxation stayed unmodified. This means in particular
5076 * that no row has been added and no bounds have been modified. For example, changing the bounds of a variable will, as
5077 * long as it was a COLUMN variable, lead to a modification in the LP such that the relaxation handler is called again
5078 * after it returned with the result code SCIP_REDUCEDDOM. If the relaxation solution should be enforced, the relaxation
5079 * handler has to produce a new solution in this case which satisfies the updated LP. If a relaxation handler should only run
5080 * once per node to compute a lower bound, it should store the node of the last relaxation call itself and return
5081 * SCIP_DIDNOTRUN for subsequent calls in the same node.
5082 *
5083 *
5084 * @section RELAX_ADDITIONALCALLBACKS Additional Callback Methods of a Relaxation Handler
5085 *
5086 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
5087 * implemented for most applications, they can be used, for example, to initialize and free private data.
5088 * Additional callbacks can either be passed directly with SCIPincludeRelax() to SCIP or via specific
5089 * <b>setter functions</b> after a call of SCIPincludeRelaxBasic(), see also @ref RELAX_INTERFACE.
5090 *
5091 * @subsection RELAXFREE
5092 *
5093 * If you are using relaxation handler data, you have to implement this method in order to free the relaxation handler
5094 * data. This can be done by the following procedure:
5095 *
5096 * @refsnippet{tests/src/relax/relax.c,SnippetRelaxFreeUnittest}
5097 *
5098 * If you have allocated memory for fields in your relaxation handler data, remember to free this memory
5099 * before freeing the relaxation handler data itself.
5100 * If you are using the C++ wrapper class, this method is not available.
5101 * Instead, just use the destructor of your class to free the member variables of your class.
5102 *
5103 * @subsection RELAXINIT
5104 *
5105 * The RELAXINIT callback is executed after the problem is transformed.
5106 * The relaxation handler may, e.g., use this call to initialize its relaxation handler data.
5107 *
5108 * @subsection RELAXCOPY
5109 *
5110 * The RELAXCOPY callback is executed when a SCIP instance is copied, e.g. to
5111 * solve a sub-SCIP. By
5112 * defining this callback as
5113 * <code>NULL</code> the user disables the execution of the specified
5114 * relaxation handler for all copied SCIP instances. This may deteriorate the performance
5115 * of primal heuristics using sub-SCIPs.
5116 *
5117 * @subsection RELAXEXIT
5118 *
5119 * The RELAXEXIT callback is executed before the transformed problem is freed.
5120 * In this method, the relaxation handler should free all resources that have been allocated for the solving process in
5121 * RELAXINIT.
5122 *
5123 * @subsection RELAXINITSOL
5124 *
5125 * The RELAXINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
5126 * begin. The relaxation handler may use this call to initialize its branch-and-bound specific data.
5127 *
5128 * @subsection REALXEXITSOL
5129 *
5130 * The RELAXEXITSOL callback is executed before the branch-and-bound process is freed.
5131 * The relaxation handler should use this call to clean up its branch-and-bound data.
5132 */
5133
5134/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5135
5136/**@page READER How to add file readers
5137 *
5138 * Mainly, file readers are called to parse an input file and generate a constraint integer programming model. They
5139 * create constraints and variables and activate variable pricers if necessary. However, they can also be called, for
5140 * example, to parse an input file containing information about a primal solution or fixing of variables. Besides that
5141 * it is possible to use some of them for writing (exporting) the problem in a specific format. \n A complete list of
5142 * all file readers contained in this release can be found \ref FILEREADERS "here".
5143 *
5144 * Since a file reader is also responsible for writing a file, the user may
5145 * ask why the readers have not the name "filehandler". This name would
5146 * represent this plugin much better than the used one.
5147 * \n
5148 * The used name "readers" is historically grown. In the beginning of SCIP
5149 * there was no need to write/export problems. Therefore, the the plugin
5150 * name "readers" was best fitting for this plugin since only reading was essential.
5151 * It turned out, however, that it is quite nice to write/export certain subproblem during
5152 * the solving process mainly for debugging. Therefore, a writing callback
5153 * was added to the "readers" plugin.
5154 *
5155 * We now explain how users can add their own file readers.
5156 * Take the file reader for MIPs in IBM's Mathematical Programming System format (src/scip/reader_mps.c) as an example.
5157 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjReader wrapper
5158 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_READER... callback methods.
5159 *
5160 * Additional documentation for the callback methods of a file reader can be found in the file type_reader.h.
5161 *
5162 * Here is what you have to do to implement a file reader named "myreader" in C:
5163 * -# Copy the template files src/scip/reader_xyz.c and src/scip/reader_xyz.h into files named
5164 * "reader_myreader.c" and "reader_myreader.h".
5165 * \n
5166 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5167 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5168 * -# Use `SCIPincludeReaderMyreader()` in order to include the reader into your SCIP instance,
5169 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5170 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5171 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myreader".
5172 * -# Adjust the \ref READER_PROPERTIES "properties of the file reader".
5173 * -# Define the \ref READER_DATA "file reader data". This is optional.
5174 * -# Implement the \ref READER_INTERFACE "interface methods".
5175 * -# Implement the \ref READER_FUNDAMENTALCALLBACKS "fundamental callback methods".
5176 * -# Implement the \ref READER_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5177 *
5178 *
5179 * @section READER_PROPERTIES Properties of a File Reader
5180 *
5181 * At the top of the new file "reader_myreader.c" you can find the file reader properties.
5182 * These are given as compiler defines.
5183 * In the C++ wrapper class, you have to provide the file reader properties by calling the constructor
5184 * of the abstract base class scip::ObjReader from within your constructor.
5185 * The properties you have to set have the following meaning:
5186 *
5187 * \par READER_NAME: the name of the file reader.
5188 * This name is used in the interactive shell to address the file reader.
5189 * Additionally, if you are searching for a file reader with SCIPfindReader(), this name is looked up.
5190 * Names have to be unique: no two file readers may have the same name.
5191 *
5192 * \par READER_DESC: the description of the file reader.
5193 * This string is printed as a description of the file reader in the interactive shell.
5194 *
5195 * \par READER_EXTENSION: the file name extension of the file reader.
5196 * Each file reader is hooked to a single file name extension. It is automatically called if the user wants to read in a
5197 * file of corresponding name. The extensions of the different file readers have to be unique.
5198 * Note that the additional extension '.gz', '.z', or '.Z' (indicating a gzip compressed file) are ignored for assigning
5199 * an input file to a reader.
5200 * \n
5201 * It is not possible to hook up a (single) file reader with more than one file extension.
5202 * It is, however, not necessary to implement the same (parsing/writing) methods more than once, if you want to
5203 * support several file extension with the same parser. To do so look at the files reader_lp.c
5204 * and reader_rlp.c. Both support the LP format.
5205 *
5206 *
5207 * @section READER_DATA File Reader Data
5208 *
5209 * Below the header "Data structures" you can find a struct which is called "struct SCIP_ReaderData".
5210 * In this data structure, you can store the data of your file reader. For example, you should store the adjustable
5211 * parameters of the file reader in this data structure.
5212 * If you are using C++, you can add file reader data as usual as object variables to your class.
5213 * \n
5214 * Defining file reader data is optional. You can leave the struct empty.
5215 *
5216 *
5217 * @section READER_INTERFACE Interface Methods
5218 *
5219 * At the bottom of "reader_myreader.c", you can find the interface method SCIPincludeReaderMyreader(),
5220 * which also appears in "reader_myreader.h".
5221 * SCIPincludeReaderMyreader() is called by the user, if (s)he wants to include the reader,
5222 * i.e., if (s)he wants to use the reader in his/her application.
5223 *
5224 * This method only has to be adjusted slightly.
5225 * It is responsible for notifying SCIP of the presence of the reader. For this, you can either call
5226 * SCIPincludeReader(),
5227 * or SCIPincludeReaderBasic() since SCIP version 3.0. In the latter variant, \ref READER_ADDITIONALCALLBACKS "additional callbacks"
5228 * must be added via setter functions as, e.g., SCIPsetReaderCopy(). We recommend this latter variant because
5229 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
5230 * variant must be manually adjusted with every SCIP release containing new callbacks for readers in order to compile.
5231 *
5232 * If you are using file reader data, you have to allocate the memory for the data at this point.
5233 * You can do this by calling:
5234 * \code
5235 * SCIP_CALL( SCIPallocBlockMemory(scip, &readerdata) );
5236 * \endcode
5237 * You also have to initialize the fields in struct SCIP_ReaderData afterwards.
5238 *
5239 * You may also add user parameters for your file reader, see the method SCIPincludeReaderLp() in
5240 * src/scip/reader_lp.c for an example.
5241 *
5242 *
5243 * @section READER_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a File Reader
5244 *
5245 * File reader plugins have no fundamental callback methods. This is due to
5246 * the fact that a file reader can be used for reading and/or writing a
5247 * file. A file reader is only useful if the reader method \ref READERREAD
5248 * and/or the writing method \ref READERWRITE is implemented. One of these
5249 * methods should be implemented for every file reader; the other callback
5250 * methods \ref READERCOPY and \ref READERFREE are optional. In the C++ wrapper class scip::ObjReader, the
5251 * scip_read() and scip_write() methods (which corresponds to the \ref
5252 * READERREAD and \ref READERWRITE callback) are virtual member
5253 * functions. At least one of them should be implemented.
5254 *
5255 * Additional documentation for the callback methods can be found in type_reader.h.
5256 *
5257 *
5258 * @section READER_ADDITIONALCALLBACKS Additional Callback Methods of a File Reader
5259 *
5260 * Additional callbacks can either be passed directly with SCIPincludeReader() to SCIP or via specific
5261 * <b>setter functions</b> after a call of SCIPincludeReaderBasic(), see also @ref READER_INTERFACE.
5262 *
5263 *
5264 * File reader plugins contain only additional callback methods, namely the methods \ref READERREAD,
5265 * \ref READERWRITE, \ref READERFREE, and \ref READERCOPY. Therefore, these are not needed to be implemented. However,
5266 * at least \ref READERREAD and/or \ref READERWRITE should be implemented (see notes
5267 * \ref READER_FUNDAMENTALCALLBACKS "above").
5268 *
5269 *
5270 * @subsection READERREAD
5271 *
5272 * The READERREAD callback is called when the user invokes SCIP to read in a file with file name extension
5273 * corresponding to the READER_EXTENSION property of the file reader. This is usually triggered by a call to the method
5274 * SCIPreadProb() or by an interactive shell command.
5275 * The READERREAD callback should parse the input file and perform the desired action, which usually means
5276 * generating a constraint integer programming model, adding a primal solution, fixing variables
5277 * in an existing model.
5278 * \n
5279 * Typical methods called by a file reader that is used to read/generate constraint
5280 * integer programming models are, for example,
5281 *
5282 * - creating an empty problem: SCIPcreateProb()
5283 * - creating the variables: SCIPcreateVar(), SCIPchgVarType(), SCIPchgVarLb(), SCIPchgVarUb(), SCIPaddVar(), and
5284 * SCIPreleaseVar()
5285 * - modifying the objective function: SCIPchgVarObj() and SCIPsetObjsense().
5286 * - creating the constraints: SCIPcreateConsLinear(), SCIPaddCoefLinear(), SCIPchgLhsLinear(), SCIPchgRhsLinear(),
5287 * SCIPaddCons(), and SCIPreleaseCons()
5288 *
5289 * Primal solutions can only be created for the transformed problem. Therefore, the user has to call SCIPtransformProb()
5290 * before (s)he reads in the file containing the solution and adds it to the solution pool via the method SCIPreadSol().
5291 *
5292 *
5293 * @subsection READERWRITE
5294 *
5295 * The READERWRITE callback is called when the user invokes SCIP to write a problem (original or transformed)
5296 * in the format the reader supports. This is only possible if this callback is implemented. To write the problem
5297 * all necessary information is given through the parameters of this callback method (see type_reader.h). This
5298 * information should be used to output the problem in the requested format. This callback method is usually
5299 * triggered by the call of the methods SCIPwriteOrigProblem(), SCIPwriteTransProblem(), SCIPprintOrigProblem(),
5300 * or SCIPprintTransProblem().
5301 * \n
5302 * A typical method called by a file reader which is used to write/export a constraint
5303 * integer programming model is SCIPinfoMessage(). This method outputs a given string into a file
5304 * or into stdout.
5305 * \n
5306 * For an example we refer to the writing method of the MPS reader (see reader_mps.c).
5307 *
5308 *
5309 * @subsection READERCOPY
5310 *
5311 * The READERCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
5312 * callback as <code>NULL</code> the user disables the execution of the specified reader for all copied SCIP
5313 * instances. The question might arise why to copy that plugin. In case of debugging it is nice to be able to
5314 * write/display the copied instances. Since the reader is in charge of that, you might want to copy the plugin. Below
5315 * you see a standard implementation.
5316 *
5317 * @refsnippet{src/scip/reader_mps.c,SnippetReaderCopyMps}
5318 *
5319 * @subsection READERFREE
5320 *
5321 * If you are using file reader data, you have to implement this method in order to free the file reader data.
5322 * This can be done by the following procedure:
5323 *
5324 * @refsnippet{src/scip/reader_mps.c,SnippetReaderFreeMps}
5325 *
5326 * If you have allocated memory for fields in your file reader data, remember to free this memory
5327 * before freeing the file reader data itself.
5328 * If you are using the C++ wrapper class, this method is not available.
5329 * Instead, just use the destructor of your class to free the member variables of your class.
5330 *
5331 */
5332
5333/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5334
5335/**@page DIALOG How to add dialogs
5336 *
5337 * SCIP comes with a command line shell which allows the user to read in problem instances, modify the solver's
5338 * parameters, initiate the optimization and display certain statistics and solution information. This shell consists
5339 * of dialogs, which are organized as a tree in SCIP. A node of this tree which is not a leaf represents a menu in
5340 * the shell and the children of this node correspond to the entries of this menu (which can again be menus). All
5341 * different dialogs are managed by a dialog handler, which, in particular, is responsible for executing the dialog
5342 * corresponding to the user's command in the shell. The concept of a dialog handler is different to that
5343 * of a constraint handler, which is used to manage objects of the same structure, see \ref CONS. In particular, SCIP
5344 * features only one dialog handler (dialog_default.h), whereas there may exist different constraint handlers.
5345 * \n
5346 * A complete list of all dialogs contained in this release can be found \ref DIALOGS "here".
5347 *
5348 * We now explain how users can extend the interactive shell by adding their own dialog.
5349 * We give the explanation for creating your own source file for each additional dialog. Of course, you can collect
5350 * different dialogs in one source file. Take src/scip/dialog_default.c, where all default dialog plugins are collected, as an
5351 * example.
5352 * As all other default plugins, the default dialog plugin and the template dialog are written in C. C++ users can easily
5353 * adapt the code by using the scip::ObjDialog wrapper base class and implement the scip_...() virtual methods instead of the
5354 * SCIP_DECL_DIALOG... callback methods.
5355 *
5356 * Additional documentation for the callback methods of a dialog can be found in the file type_dialog.h.
5357 *
5358 * Here is what you have to do to add a dialog (assuming your dialog is named "mydialog"):
5359 * -# Copy the template files src/scip/dialog_xyz.c and src/scip/dialog_xyz.h into files named "dialog_mydialog.c"
5360 * and "dialog_mydialog.h".
5361 * \n
5362 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5363 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5364 * -# Use `SCIPincludeDialogMydialog()` in order to include the dialog handler into your SCIP instance,
5365 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5366 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5367 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mydialog".
5368 * -# Adjust the \ref DIALOG_PROPERTIES "properties of the dialog".
5369 * -# Define the \ref DIALOG_DATA "dialog data". This is optional.
5370 * -# Implement the \ref DIALOG_INTERFACE "interface methods".
5371 * -# Implement the \ref DIALOG_FUNDAMENTALCALLBACKS "fundamental callback methods".
5372 * -# Implement the \ref DIALOG_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5373 *
5374 *
5375 * @section DIALOG_PROPERTIES Properties of a Dialog
5376 *
5377 * At the top of the new file "dialog_mydialog.c" you can find the dialog properties.
5378 * These are given as compiler defines.
5379 * In the C++ wrapper class, you have to provide the dialog properties by calling the constructor
5380 * of the abstract base class scip::ObjDialog from within your constructor.
5381 * The properties you have to set have the following meaning:
5382 *
5383 * \par DIALOG_NAME: the name of the dialog.
5384 * In the interactive shell, this name appears as the command name of the dialog in the parent dialog.
5385 * Additionally, if you are searching an entry in a menu with SCIPdialogFindEntry(), this name is looked up.
5386 * Names within one menu have to be unique: no two dialogs in the same menu may have the same name.
5387 *
5388 * \par DIALOG_DESC: the description of the dialog.
5389 * This string is printed as a description of the dialog in the interactive shell if the additional
5390 * callback method \ref DIALOGDESC is not implemented.
5391 *
5392 * \par DIALOG_ISSUBMENU: whether the dialog is a (sub)menu.
5393 * This parameter states whether the dialog is a menu in the interactive shell, i.e., is the parent of further
5394 * dialogs.
5395 *
5396 *
5397 * @section DIALOG_DATA Dialog Data
5398 *
5399 * Below the header "Data structures" you can find a struct which is called "struct SCIP_DialogData".
5400 * In this data structure, you can store the data of your dialog.
5401 * If you are using C++, you can add dialog data as usual as object variables to your class.
5402 * \n
5403 * Defining dialog data is optional. You can leave the struct empty.
5404 *
5405 *
5406 * @section DIALOG_INTERFACE Interface Methods
5407 *
5408 * At the bottom of "dialog_mydialog.c" you can find the interface method SCIPincludeDialogMydialog(), which also appears
5409 * in "dialog_mydialog.h".
5410 * \n
5411 * This method only has to be adjusted slightly.
5412 * It is responsible for notifying SCIP of the presence of the dialog, which can be done by the following lines of code:
5413 *
5414 * @refsnippet{src/scip/dialog_xyz.c,SnippetDialogAddXyz}
5415 *
5416 * Here "parentdialog" has to be an existing dialog which is defined to be a menu (see DIALOG_ISSUBMENU), e.g.,
5417 * the default root dialog. The method SCIPgetRootDialog() returns the root dialog.
5418 *
5419 * 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
5420 * his/her application.
5421 * Note that in order to be able to link the new dialog to an existing default dialog
5422 * (except the root dialog) it has to be included <b>after the
5423 * default dialogs plugin</b>, i.e., the SCIPincludeDialogMydialog() call has to occur after the
5424 * SCIPincludeDialogDefault() call. The SCIPincludeDialogDefault() method is called from within the SCIPincludeDefaultPlugins()
5425 * method. Therefore, it suffices to include your dialog plugins after you have called SCIPincludeDefaultPlugins().
5426 * In case you want to add a dialog to the <b>root dialog</b>, you just use the following
5427 * lines of code to get/create the root dialog.
5428 *
5429 * @refsnippet{tests/src/misc/snippets.c,SnippetDialogCreate}
5430 *
5431 * Therefore, in this case you do not have to worry about the calls of
5432 * SCIPincludeDialogDefault() and SCIPincludeDefaultPlugins() .
5433 *
5434 * If you are using dialog data, you have to allocate the memory for the data at this point.
5435 * You can do this by calling:
5436 * \code
5437 * SCIP_CALL( SCIPallocBlockMemory(scip, &dialogdata) );
5438 * \endcode
5439 * You also have to initialize the fields in struct SCIP_DialogData afterwards.
5440 *
5441 * Consider the following example. The user wants to add a "drawgraph" command to the root menu of SCIP.
5442 * (S)he copies the "dialog_xyz.c" and "dialog_xyz.h" files into files "dialog_drawgraph.c" and "dialog_drawgraph.h", respectively.
5443 * Then, (s)he puts the following code into the SCIPincludeDialogDrawgraph() method, compare SCIPincludeDialogDefault() in
5444 * src/scip/dialog_default.c:
5445 * @refsnippet{tests/src/misc/snippets.c,SnippetDialogInclude}
5446 *
5447 * Using this code, it is even possible to call SCIPincludeDialogDrawgraph() before including the default dialog plugins,
5448 * and you can also call it multiple times without causing inconsistencies in the dialog structure.
5449 *
5450 *
5451 * @section DIALOG_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Dialog
5452 *
5453 * Dialogs have only one fundamental callback method, namely the \ref DIALOGEXEC method.
5454 * This method has to be implemented for every dialog; the other callback methods are optional.
5455 * In the C++ wrapper class scip::ObjDialog, the scip_exec() method (which corresponds to the \ref DIALOGEXEC callback) is a virtual
5456 * abstract member function.
5457 * You have to implement it in order to be able to construct an object of your dialog class.
5458 *
5459 * Additional documentation for the callback methods can be found in type_dialog.h.
5460 *
5461 * @subsection DIALOGEXEC
5462 *
5463 * The DIALOGEXEC method is invoked, if the user selected the dialog's command name in the parent's menu. It should
5464 * execute what is stated in DIALOG_DESC, e.g., the display constraint handlers dialog should display information about
5465 * the constraint handlers included in SCIP, see src/scip/dialog_default.c.
5466 *
5467 * For typical methods called by the execution method, have a look at src/scip/dialog_default.c.
5468 *
5469 * The callback has to return which dialog should be processed next. This can be, for example, the root dialog
5470 * (SCIPdialoghdlrGetRoot()), the parent dialog (SCIPdialogGetParent()) or NULL, which stands for closing the interactive
5471 * shell.
5472 *
5473 *
5474 * @section DIALOG_ADDITIONALCALLBACKS Additional Callback Methods of a Dialog
5475 *
5476 * The additional callback methods do not need to be implemented in every case.
5477 * They can be used, for example, to free private data.
5478 *
5479 * @subsection DIALOGFREE
5480 *
5481 * If you are using dialog data, you have to implement this method in order to free the dialog data.
5482 * This can be done by the following procedure:
5483 * @refsnippet{tests/src/misc/snippets.c,SnippetDialogFree}
5484 *
5485 * If you have allocated memory for fields in your dialog data, remember to free this memory
5486 * before freeing the dialog data itself.
5487 * If you are using the C++ wrapper class, this method is not available.
5488 * Instead, just use the destructor of your class to free the member variables of your class.
5489 *
5490 * @subsection DIALOGDESC
5491 *
5492 * This method is called when the help menu of the parent is displayed. It should output (usually a single line of)
5493 * information describing the meaning of the dialog.
5494 * \n
5495 * If this callback is not implemented, the description string of the dialog (DIALOG_DESC) is displayed instead.
5496 *
5497 * @subsection DIALOGCOPY
5498 *
5499 * The DIALOGCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
5500 * callback as <code>NULL</code> the user disables the execution of this dialog for all copied SCIP instances. In
5501 * general there is no need to copy any dialog since it is most unlikely to start the interactive shell of the copied
5502 * instances.
5503 *
5504 */
5505
5506/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5507
5508/**@page DISP How to add display columns
5509 *
5510 * While solving a constraint integer program, SCIP displays status information in a column-like fashion. The current
5511 * number of processed branching tree nodes, the solving time, and the relative gap between primal and dual bound are
5512 * examples of such display columns. There already exists a wide variety of display columns which can be activated or
5513 * deactivated on demand, see src/scip/disp_default.c. Additionally, the user can implement his/her own display columns
5514 * in order to track problem or algorithm specific values.
5515 * \n
5516 * A complete list of all displays contained in this release can be found \ref DISPLAYS "here".
5517 *
5518 * We now explain how users can add their own display columns.
5519 * We give the explanation for creating your own source file for each additional display column. Of course, you can collect
5520 * different additional display columns in one source file.
5521 * Take src/scip/disp_default.c, where all default display columns are collected, as an example.
5522 * As all other default plugins, the default display column plugins and the display column template are written in C.
5523 * C++ users can easily adapt the code by using the scip::ObjDisp wrapper base class and implement the scip_...() virtual methods
5524 * instead of the SCIP_DECL_DISP... callback methods.
5525 *
5526 *
5527 * Additional documentation for the callback methods of a display column can be found in the file type_disp.h.
5528 *
5529 * Here is what you have to do to implement a display column (assuming your display column is named "mydisplaycolumn"):
5530 * -# Copy the template files src/scip/disp_xyz.c and src/scip/disp_xyz.h into files named "disp_mydisplaycolumn.c"
5531 * and "disp_mydisplaycolumn.h".
5532 \n
5533 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5534 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5535 * -# Use `SCIPincludeDispMydisplaycolumn()` in order to include the display column into your SCIP instance,
5536 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5537 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5538 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mydisplaycolumn".
5539 * -# Adjust the \ref DISP_PROPERTIES "properties of the display column".
5540 * -# Define the \ref DISP_DATA "display column data". This is optional.
5541 * -# Implement the \ref DISP_INTERFACE "interface methods".
5542 * -# Implement the \ref DISP_FUNDAMENTALCALLBACKS "fundamental callback methods".
5543 * -# Implement the \ref DISP_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5544 *
5545 *
5546 * @section DISP_PROPERTIES Properties of a Display Column
5547 *
5548 * At the top of the new file "disp_mydisplaycolumn.c" you can find the display column properties.
5549 * These are given as compiler defines.
5550 * In the C++ wrapper class, you have to provide the display column properties by calling the constructor
5551 * of the abstract base class scip::ObjDisp from within your constructor.
5552 * The properties you have to set have the following meaning:
5553 *
5554 * \par DISP_NAME: the name of the display column.
5555 * This name is used in the interactive shell to address the display column.
5556 * Additionally, if you are searching for a display column with SCIPfindDisp(), this name is looked up.
5557 * Names have to be unique: no two display columns may have the same name.
5558 *
5559 * \par DISP_DESC: the description of the display column.
5560 * This string is printed as a description of the display column in the interactive shell.
5561 *
5562 * \par DISP_HEADER: the header of the display column.
5563 * This string is printed as the header of the display column in the status information display.
5564 *
5565 * \par DISP_WIDTH: the width of the display column.
5566 * This parameter defines the width (number of characters) of the display column. The value of the parameter has to be
5567 * greater than or equal to the number of characters in the header string.
5568 *
5569 * \par DISP_PRIORITY: the priority of the display column.
5570 * The total width of status information lines is bounded by the parameter "display width". The display columns actually contained
5571 * in the status information display are selected in decreasing order of their priority. Furthermore, the user can force
5572 * columns to be displayed or not to be displayed in the status information display. For that, (s)he has to switch the value
5573 * of the display column's parameter "active" from "auto" (its default value) to "on" or "off", respectively.
5574 *
5575 * \par DISP_POSITION: the relative position of the display column.
5576 * In the status information display, the display columns are arranged from left to right in increasing order of their
5577 * relative position.
5578 *
5579 * \par DISP_STRIPLINE: the default for whether the display column should be separated with a line from its right neighbor.
5580 * This parameter states whether the display column should be separated with the string "|" from its right neighbor. In so
5581 * doing, the clearness of the status information display may improve.
5582 *
5583 * @section DISP_DATA Display Column Data
5584 *
5585 * Below the header "Data structures" you can find a struct which is called "struct SCIP_DispData".
5586 * In this data structure, you can store the data of your display column. For example, you should store the adjustable
5587 * parameters of the display column in this data structure.
5588 * If you are using C++, you can add display column data as usual as object variables to your class.
5589 * \n
5590 * Defining display column data is optional. You can leave the struct empty.
5591 *
5592 *
5593 * @section DISP_INTERFACE Interface Methods
5594 *
5595 * At the bottom of "disp_mydisplaycolumn.c" you can find the interface method SCIPincludeDispMydisplaycolumn(), which also
5596 * appears in "disp_mydisplaycolumn.h".
5597 * \n
5598 * This method only has to be adjusted slightly.
5599 * It is responsible for notifying SCIP of the presence of the display column by calling the method
5600 * SCIPincludeDisp().
5601 *
5602 * 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
5603 * application.
5604 *
5605 * If you are using display column data, you have to allocate the memory for the data at this point.
5606 * You can do this by calling:
5607 * \code
5608 * SCIP_CALL( SCIPallocBlockMemory(scip, &dispdata) );
5609 * \endcode
5610 * You also have to initialize the fields in struct SCIP_DispData afterwards.
5611 *
5612 * Although this is very uncommon, you may also add user parameters for your display column, see the method
5613 * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
5614 *
5615 *
5616 * @section DISP_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Display Column
5617 *
5618 * Display column plugins have only one fundamental callback method, namely the \ref DISPOUTPUT method.
5619 * This method has to be implemented for every display column; the other callback methods are optional.
5620 * In the C++ wrapper class scip::ObjDisp, the scip_output() method (which corresponds to the \ref DISPOUTPUT callback) is a virtual
5621 * abstract member function.
5622 * You have to implement it in order to be able to construct an object of your display column class.
5623 *
5624 * Additional documentation for the callback methods can be found in type_disp.h.
5625 *
5626 * @subsection DISPOUTPUT
5627 *
5628 * The DISPOUTPUT callback is called after each pricing loop during node processing and after a node has been processed.
5629 * In addition, at the root node, the callback is executed after each iteration of the price-and-cut loop.
5630 * It should write the display column information for the current node to a given output file stream.
5631 *
5632 * Typical methods called by a display column are, for example, SCIPdispLongint(), SCIPdispInt(), SCIPdispTime(), and
5633 * SCIPinfoMessage().
5634 *
5635 *
5636 * @section DISP_ADDITIONALCALLBACKS Additional Callback Methods of a Display Column
5637 *
5638 * The additional callback methods do not need to be implemented in every case.
5639 * They can be used, for example, to initialize and free private data.
5640 *
5641 * @subsection DISPCOPY
5642 *
5643 * The DISPCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this callback
5644 * as <code>NULL</code> the user disables the execution of the specified column. In general it is probably not needed to
5645 * implement that callback since the output of the copied instance is usually suppressed. In the other case or for
5646 * debugging the callback should be implement.
5647 *
5648 *
5649 * @subsection DISPFREE
5650 *
5651 * If you are using display column data, you have to implement this method in order to free the display column data.
5652 * This can be done by the following procedure:
5653 * @refsnippet{tests/src/misc/snippets.c,SnippetDispFree}
5654 *
5655 * If you have allocated memory for fields in your display column data, remember to free this memory
5656 * before freeing the display column data itself.
5657 * If you are using the C++ wrapper class, this method is not available.
5658 * Instead, just use the destructor of your class to free the member variables of your class.
5659 *
5660 * @subsection DISPINIT
5661 *
5662 * The DISPINIT callback is executed after the problem is transformed.
5663 * The display column may, e.g., use this call to initialize its display column data.
5664 *
5665 * @subsection DISPEXIT
5666 *
5667 * The DISPEXIT callback is executed before the transformed problem is freed.
5668 * In this method, the display column should free all resources that have been allocated for the solving process in
5669 * \ref DISPINIT.
5670 *
5671 * @subsection DISPINITSOL
5672 *
5673 * The DISPINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
5674 * begin. The display column may use this call to initialize its branch-and-bound specific data.
5675 *
5676 * @subsection DISPEXITSOL
5677 *
5678 * The DISPEXITSOL callback is executed before the branch-and-bound process is freed. The display column should use this
5679 * call to clean up its branch-and-bound specific data.
5680 */
5681
5682/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5683
5684/**@page EVENT How to add event handler
5685 *
5686 * While solving a constraint integer program, SCIP drops thousands of events such as SCIP_EVENTTYPE_VARFIXED (a
5687 * complete list of all events is given in type_event.h). These events can be caught and used to do something after a
5688 * certain event happens. Events can be used to speed up the solution process. For example, the set partitioning
5689 * constraint is only worth propagating if one of the involved variables is fixed. This can be detected by
5690 * catching the event SCIP_EVENTTYPE_VARFIXED. To be able to catch an event it is necessary to write an event handler
5691 * which defines what to do after a certain event was caught.
5692 *
5693 * We now explain how users can add their own event handlers. We give the explanation for creating your own
5694 * source file for each additional event handler. Of course, you can collect different event handlers in one source file
5695 * or you can put the event handler directly into the constraint handler. In a \ref EVENTUSAGE "second step" we discuss
5696 * the usage of an event handler. This means how to catch and drop events. \ref EVENTTYPES "Finally", we give some notes on the existing
5697 * types of events.
5698 *
5699 * Take src/scip/cons_logior.c, where the event handler is directly included into the constraint handler. As all other
5700 * default plugins, the event handlers are written in C. C++ users can easily adapt the code by using the scip::ObjEventhdlr
5701 * wrapper base class and implement the scip_...() virtual methods instead of the SCIP_DECL_EVENT... callback methods.
5702 *
5703 * Additional documentation for the callback methods of an event handler can be found in the file type_event.h. There is
5704 * also an example written in C which deals with an event handler. You find this example in the directory
5705 * "examples/Eventhdlr/". An C++ example can be found within the TSP project (examples/TSP/src/EventhdlrNewSol.cpp).
5706 *
5707 * Here is what you have to do to implement an event handler (assuming your event handler is named "bestsol"):
5708 * -# Copy the template files src/scip/event_xyz.c and src/scip/event_xyz.h into files named "event_bestsol.c"
5709 * and "event_bestsol.h".
5710 \n
5711 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5712 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5713 * -# Use `SCIPincludeEventBestsol()` in order to include the event handler into your SCIP instance,
5714 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5715 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5716 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "bestsol".
5717 * -# Adjust the \ref EVENTHDLR_PROPERTIES "properties of the event handler".
5718 * -# Implement the \ref EVENT_INTERFACE "interface methods".
5719 * -# Implement the \ref EVENT_FUNDAMENTALCALLBACKS "fundamental callback methods".
5720 * -# Implement the \ref EVENT_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5721 *
5722 *
5723 * @section EVENTHDLR_PROPERTIES Properties of a Event Handler
5724 *
5725 * At the top of the new file "event_bestsol.c" you can find the event handler properties.
5726 * These are given as compiler defines.
5727 * In the C++ wrapper class, you have to provide the event handler properties by calling the constructor
5728 * of the abstract base class scip::ObjEventhdlr from within your constructor.
5729 * The properties you have to set have the following meaning:
5730 *
5731 * \par EVENT_NAME: the name of the event handler.
5732 * This name has to be unique with respect to all other event handlers. If you are searching for an event handler with
5733 * SCIPfindEventhdlr(), this name is looked up.
5734 *
5735 * \par EVENT_DESC: the description of the event handler.
5736 * This string is printed as a description of the event handler.
5737 *
5738 * @section EVENTHDLR_DATA Event Handler Data
5739 *
5740 * Below the header "Data structures" you can find a struct which is called "struct SCIP_EventhdlrData".
5741 * In this data structure, you can store the data of your event handler. For example, you should store the adjustable
5742 * parameters of the event handler in this data structure.
5743 * If you are using C++, you can add event handler data as usual as object variables to your class.
5744 * \n
5745 * Defining event handler data is optional. You can leave the struct empty.
5746 *
5747 *
5748 * @section EVENT_INTERFACE Interface Methods
5749 *
5750 * At the bottom of "event_bestsol.c", you can find the interface method SCIPincludeEventBestsol(),
5751 * which also appears in "event_bestsol.h".
5752 * SCIPincludeEventBestsol() is called by the user, if (s)he wants to include the event handler,
5753 * i.e., if (s)he wants to use the event handler in his/her application.
5754 *
5755 * This method only has to be adjusted slightly.
5756 * It is responsible for notifying SCIP of the presence of the event handler. For this, you can either call
5757 * SCIPincludeEventhdlr(),
5758 * or SCIPincludeEventhdlrBasic() since SCIP version 3.0. In the latter variant, \ref EVENT_ADDITIONALCALLBACKS "additional callbacks"
5759 * must be added via setter functions as, e.g., SCIPsetReaderCopy(). We recommend this latter variant because
5760 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
5761 * variant must be manually adjusted with every SCIP release containing new callbacks for event handlers in order to compile.
5762 *
5763 * If you are using event handler data, you have to allocate the memory for the data at this point.
5764 * You can do this by calling:
5765 * \code
5766 * SCIP_CALL( SCIPallocBlockMemory(scip, &eventhdlrdata) );
5767 * \endcode
5768 * You also have to initialize the fields in struct SCIP_EventhdlrData afterwards.
5769 *
5770 * Although this is very uncommon, you may also add user parameters for your event handler, see the method
5771 * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
5772 *
5773 *
5774 * @section EVENT_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Event Handler
5775 *
5776 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
5777 * an operational algorithm.
5778 * They are passed together with the event handler itself to SCIP using SCIPincludeEventhdlr() or SCIPincludeEventhdlrBasic(),
5779 * see @ref EVENT_INTERFACE.
5780 *
5781 *
5782 * Event handler plugins have only one fundamental callback method, namely the \ref EVENTEXEC method. This method has
5783 * to be implemented for every event handler; the other callback methods are optional. In the C++ wrapper class
5784 * scip::ObjEventhdlr, the scip_exec() method (which corresponds to the \ref EVENTEXEC callback) is a virtual abstract member
5785 * function. You have to implement it in order to be able to construct an object of your event handler class.
5786 *
5787 * Additional documentation for the callback methods can be found in type_event.h.
5788 *
5789 * @subsection EVENTEXEC
5790 *
5791 * The EVENTEXEC callback is called after the requested event happened. Then the event handler can do some action in
5792 * reaction to the event.
5793 *
5794 * Typical the execution method sets a parameter to TRUE to indicate later in solving process that something happened
5795 * which should be analyzed further. In the \ref cons_knapsack.h "knapsack constraint handler" you find such a typical
5796 * example.
5797 *
5798 * @section EVENT_ADDITIONALCALLBACKS Additional Callback Methods of a Event Handler
5799 *
5800 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
5801 * implemented for most applications, they can be used, for example, to initialize and free private data.
5802 * Additional callbacks can either be passed directly with SCIPincludeEventhdlr() to SCIP or via specific
5803 * <b>setter functions</b> after a call of SCIPincludeEventhdlrBasic(), see also @ref EVENT_INTERFACE.
5804 *
5805 * @subsection EVENTCOPY
5806 *
5807 * The EVENTCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
5808 * callback as <code>NULL</code> the user disables the execution of the specified event handler for all copied SCIP
5809 * instances. Note that in most cases the event handler in the copied instance will be initialize by those objects (such
5810 * as constraint handlers or propagators) which need this event handler (see \ref cons_knapsack.h). In these cases the copy
5811 * callback can be ignored. In case of general events, such as a new best solution being found
5812 * (SCIP_EVENTTYPE_BESTSOLFOUND), you might want to implement that callback. The event handler example which you find
5813 * in the directory "examples/Eventhdlr/" uses that callback.
5814 *
5815 * @refsnippet{src/scip/event_softtimelimit.c,SnippetEventCopySofttimelimit}
5816 *
5817 * @subsection EVENTFREE
5818 *
5819 * If you are using event handler data, you have to implement this method in order to free the event handler data.
5820 * This can be done by the following procedure:
5821 *
5822 * @refsnippet{src/scip/event_softtimelimit.c,SnippetEventFreeSofttimelimit}
5823 *
5824 * If you have allocated memory for fields in your event handler data, remember to free this memory
5825 * before freeing the event handler data itself.
5826 * If you are using the C++ wrapper class, this method is not available.
5827 * Instead, just use the destructor of your class to free the member variables of your class.
5828 *
5829 *
5830 * @subsection EVENTINIT
5831 *
5832 * The EVENTINIT callback is executed after the problem is transformed.
5833 * The event handler may, e.g., use this call to initialize its event handler data.
5834 *
5835 * @subsection EVENTEXIT
5836 *
5837 * The EVENTEXIT callback is executed before the transformed problem is freed.
5838 * In this method, the event handler should free all resources that have been allocated for the solving process in
5839 * \ref EVENTINIT.
5840 *
5841 * @subsection EVENTINITSOL
5842 *
5843 * The EVENTINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
5844 * begin. The event handler may use this call to initialize its branch-and-bound specific data.
5845 *
5846 * @subsection EVENTEXITSOL
5847 *
5848 * The EVENTEXITSOL callback is executed before the branch-and-bound process is freed. The event handler should use this
5849 * call to clean up its branch-and-bound specific data.
5850 *
5851 * @section EVENTUSAGE Catching and Dropping Events
5852 *
5853 * After you have implemented the event handler, you have to tell SCIP for which events this event handler should be
5854 * used. This can be a general events, such as <code>SCIP_EVENTTYPE_BESTSOLFOUND</code>, or a variable event which is the most common
5855 * way.
5856 *
5857 * In case of a general (not variable) event you use the function SCIPcatchEvent() to attach to an event and
5858 * SCIPdropEvent() to release this event later.
5859 *
5860 * \code
5861 * SCIP_CALL( SCIPcatchEvent( scip, SCIP_EVENTTYPE_BESTSOLFOUND, eventhdlr, NULL, NULL) );
5862 * \endcode
5863 *
5864 * \code
5865 * SCIP_CALL( SCIPdropEvent( scip, SCIP_EVENTTYPE_BESTSOLFOUND, eventhdlr, NULL, NULL) );
5866 * \endcode
5867 *
5868 * If you want trigger some variable event, you use the method SCIPcatchVarEvent() to attach the variable event and
5869 * SCIPdropVarEvent() to drop it later.
5870 *
5871 * \code
5872 * SCIP_CALL( SCIPcatchVarEvent( scip, var, SCIP_EVENTTYPE_VARFIXED, eventhdlr, NULL, NULL) );
5873 * \endcode
5874 *
5875 * \code
5876 * SCIP_CALL( SCIPdropVarEvent( scip, var, SCIP_EVENTTYPE_VARFIXED, eventhdlr, NULL, NULL) );
5877 * \endcode
5878 *
5879 * @section EVENTTYPES Event types
5880 *
5881 * All available events are listed in type_event.h. There are atomic events such as <code>SCIP_EVENTTYPE_VARFIXED</code>
5882 * and combined events such as <code>SCIP_EVENTTYPE_VARCHANGED</code>. The events are encoded via bit masks. Each atomic
5883 * event has a unique power of two. This enables combination of the atomic events.
5884 *
5885 * SCIP only throws atomic events. However, an event handler might be interested in bunch of events. Through the
5886 * underlying bit masks it is possible to combine the atomic events. For example, <code>SCIP_EVENTTYPE_VARCHANGED</code>
5887 * is an event which combines the events <code>SCIP_EVENTTYPE_VARFIXED</code>, <code>SCIP_EVENTTYPE_VARUNLOCKED</code>,
5888 * <code>SCIP_EVENTTYPE_OBJCHANGED</code>, <code>SCIP_EVENTTYPE_GBDCHANGED</code>,
5889 * <code>SCIP_EVENTTYPE_DOMCHANGED</code>, and <code>SCIP_EVENTTYPE_IMPLADDED</code>.
5890 *
5891 * \code
5892 * #define SCIP_EVENTTYPE_VARCHANGED (SCIP_EVENTTYPE_VARFIXED | SCIP_EVENTTYPE_VARUNLOCKED | SCIP_EVENTTYPE_OBJCHANGED
5893 * | SCIP_EVENTTYPE_GBDCHANGED | SCIP_EVENTTYPE_DOMCHANGED | SCIP_EVENTTYPE_IMPLADDED)
5894 * \endcode
5895 *
5896 * Depending on the event type, the event offers different information. The methods which can be used to gain
5897 * access to this information are given in pub_event.h.
5898 *
5899 */
5900
5901/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5902
5903/**@page NLPI How to add interfaces to nonlinear programming solvers
5904 *
5905 * NLPIs are used to interface a solver for nonlinear programs (NLP).
5906 * It is used, e.g., to solve convex relaxations of the problem or to find locally optimal solutions of
5907 * nonlinear relaxations or subproblems.
5908 * The NLPI has been designed such that it can be used independently of a SCIP problem.
5909 *
5910 * While the NLPI itself corresponds to the solver interface, the NLPIPROBLEM corresponds to the
5911 * (solver specific) representation of a concrete nonlinear program.
5912 * An NLP is specified as a set of indexed variables with variable bounds, an objective function,
5913 * and a set of constraints, where each constraint is specified as a function which is restricted to lie
5914 * between given left and right hand sides (possibly infinite).
5915 * A function consists of a linear and a nonlinear part.
5916 * The linear part is specified via variable indices and coefficients, while the nonlinear part is specified via an expression.
5917 * That is, the user of the NLPI does not provide function evaluation callbacks but an algebraic representation of the NLP.
5918 * Interfaces for solvers that require function evaluations can make use of the \ref NLPIOracle "NLPIORACLE", which
5919 * provides functionality to store a NLP and compute functions values, gradients, Jacobians, and Hessians.
5920 * See the interface to Ipopt for an example on how to use the NLPIORACLE.
5921 *
5922 * A complete list of all NLPIs contained in this release can be found \ref NLPIS "here".
5923 *
5924 * We now explain how users can add their own NLP solver interface.
5925 * Take the interface to Ipopt (src/scip/nlpi_ipopt.cpp) as an example.
5926 * Unlike most other plugins, it is written in C++.
5927 * Additional documentation for the callback methods of an NLPI, in particular for their input parameters,
5928 * can be found in the file \ref type_nlpi.h.
5929 *
5930 * Here is what you have to do to implement an NLPI:
5931 * -# 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".
5932 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5933 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5934 * -# Use `SCIPincludeNlpSolverMysolver()` in order to include the NLPI into your SCIP instance,
5935 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5936 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5937 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mysolver".
5938 * -# Adjust the properties of the nlpi (see \ref NLPI_PROPERTIES).
5939 * -# Define the NLPI and NLPIPROBLEM data (see \ref NLPI_DATA).
5940 * -# Implement the interface methods (see \ref NLPI_INTERFACE).
5941 * -# Implement the fundamental callback methods (see \ref NLPI_FUNDAMENTALCALLBACKS).
5942 * -# Implement the additional callback methods (see \ref NLPI_ADDITIONALCALLBACKS). This is optional.
5943 *
5944 *
5945 * @section NLPI_PROPERTIES Properties of an NLPI
5946 *
5947 * At the top of the new file "nlpi_mysolver.c", you can find the NLPI properties.
5948 * These are given as compiler defines.
5949 * The properties you have to set have the following meaning:
5950 *
5951 * \par NLPI_NAME: the name of the NLP solver interface.
5952 * This name is used in the interactive shell to address the NLPI.
5953 * Additionally, if you are searching for an NLPI with SCIPfindNlpi(), this name is looked up.
5954 * Names have to be unique: no two NLPIs may have the same name.
5955 *
5956 * \par NLPI_DESC: the description of the NLPI.
5957 * This string is printed as a description of the NLPI in the interactive shell.
5958 *
5959 * \par NLPI_PRIORITY: the priority of the NLPI.
5960 * If an NLP has to be solved, an NLP solver has to be selected.
5961 * By default, the solver with the NLPI with highest priority is selected.
5962 * The priority of an NLPI should be set according to performance of the solver:
5963 * solvers that provide fast algorithms that are usually successful on a wide range of problems should have a high priority.
5964 * An easy way to list the priorities of all NLPIs is to type "display nlpis" in the interactive shell of SCIP.
5965 *
5966 * @section NLPI_DATA NLPI Data
5967 *
5968 * Below the header "Data structures" you can find structs which are called `struct SCIP_NlpiData` and `struct SCIP_NlpiProblem`.
5969 * In these data structures, you can store the data of your solver interface and of a specific NLP problem.
5970 * For example, you could store a pointer to your NLP solver environment object in the `SCIP_NlpiData` data structure
5971 * and store a pointer to an NLPIORACLE in the `SCIP_NlpiProblem` data structure.
5972 *
5973 * @section NLPI_INTERFACE Interface Methods
5974 *
5975 * At the bottom of "nlpi_mysolver.c", you can find the interface method SCIPincludeNlpSolverXyz(),
5976 * which also appears in "nlpi_mysolver.h".
5977 *
5978 * This method only has to be adjusted slightly.
5979 * It is responsible for creating an NLPI that contains all properties and callback methods of your
5980 * solver interface and included it into SCIP by calling the method SCIPincludeNlpi().
5981 * SCIPincludeNlpSolverXyz() is called by the user (e.g., SCIP), if (s)he wants to use this solver interface in his/her application.
5982 *
5983 * If you are using NLPI data, you have to allocate the memory for the data at this point.
5984 * You can do this by calling:
5985 * \code
5986 * SCIP_CALL( SCIPallocBlockMemory(scip, &nlpidata) );
5987 * \endcode
5988 * You also have to initialize the fields in struct SCIP_NlpiData afterwards. For freeing the
5989 * NLPI data, see \ref NLPIFREE.
5990 *
5991 *
5992 * @section NLPI_FUNDAMENTALCALLBACKS Fundamental Callback Methods of an NLPI
5993 *
5994 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
5995 * an operational algorithm. Most NLPI callbacks are fundamental.
5996 *
5997 * Additional documentation of the callback methods, in particular to their input parameters,
5998 * can be found in \ref type_nlpi.h.
5999 *
6000 * @subsection NLPIFREE
6001 *
6002 * The NLPIFREE callback is executed if the NLP solver interface data structure should be freed, e.g., when a SCIP instance is freed.
6003 *
6004 * @subsection NLPICREATEPROBLEM
6005 *
6006 * The NLPICREATEPROBLEM callback is executed if a particular NLP problem is to be created.
6007 * The callback method should initialize a SCIP_NlpiProblem struct here that corresponds to an empty NLP.
6008 *
6009 * @subsection NLPIFREEPROBLEM
6010 *
6011 * The NLPIFREEPROBLEMPOINTER callback is executed if a particular NLP problem is to be freed.
6012 * The callback method should free a SCIP_NlpiProblem struct here.
6013 *
6014 * @subsection NLPIADDVARS
6015 *
6016 * The NLPIADDVARS callback is executed if a set of variables with lower and upper bounds and names should be added to a particular NLP.
6017 * The callback method must add the new variables behind the previously added variables, if any.
6018 * If NULL is given for the lower bounds arguments, -infinity is assumed as lower bound for each new variable.
6019 * If NULL is given for the upper bounds arguments, +infinity is assumed as upper bound for each new variable.
6020 * It is also permitted to use NULL for the names argument.
6021 *
6022 * @subsection NLPIADDCONSTRAINTS
6023 *
6024 * The NLPIADDCONSTRAINTS callback is executed if a set of constraints should be added to a particular NLP.
6025 * Constraints are specified by providing left- and right-hand-sides, linear coefficients, expressions, and constraint names.
6026 * All of these arguments are optional, giving NULL for left-hand-sides corresponds to -infinity, giving NULL for right-hand-sides corresponds to +infinity.
6027 *
6028 * @subsection NLPISETOBJECTIVE
6029 *
6030 * The NLPISETOBJECTIVE callback is executed to set the objective function of a particular NLP.
6031 *
6032 * @subsection NLPICHGVARBOUNDS
6033 *
6034 * The NLPICHGVARBOUNDS callback is executed to change the bounds on a set of variables of an NLP.
6035 *
6036 * @subsection NLPICHGCONSSIDES
6037 *
6038 * The NLPICHGCONSSIDES callback is executed to change the sides on a set of constraints of an NLP.
6039 *
6040 * @subsection NLPIDELVARSET
6041 *
6042 * The NLPIDELVARSET callback is executed to delete a set of variables from an NLP.
6043 * The caller provides an array in which for each variable it is marked whether it should be deleted.
6044 * In the same array, the method should return the new position of each variable in the NLP, or -1 if it was deleted.
6045 *
6046 * @subsection NLPIDELCONSSET
6047 *
6048 * The NLPIDELCONSSET callback is executed to delete a set of constraints from an NLP.
6049 * The caller provides an array in which for each constraint it is marked whether it should be deleted.
6050 * In the same array, the method should return the new position of each constraint in the NLP, or -1 if it was deleted.
6051 *
6052 * @subsection NLPICHGLINEARCOEFS
6053 *
6054 * The NLPICHGLINEARCOEFS callback is executed to change the coefficients in the linear part of the objective function or a constraint of an NLP.
6055 *
6056 * @subsection NLPICHGEXPR
6057 *
6058 * The NLPICHGEXPR callback is executed to replace the expression of the objective function or a constraint of an NLP.
6059 *
6060 * @subsection NLPICHGOBJCONSTANT
6061 *
6062 * The NLPICHGOBJCONSTANT callback is executed to change the constant offset of the objective function of an NLP.
6063 *
6064 * @subsection NLPISOLVE
6065 *
6066 * The NLPISOLVE callback is executed when an NLP should be solved.
6067 * The solver may use the initial guess provided by \ref NLPISETINITIALGUESS as starting point.
6068 * The status of the solving process and solution can be requested by
6069 * \ref NLPIGETSOLSTAT, \ref NLPIGETTERMSTAT, \ref NLPIGETSOLUTION, and \ref NLPIGETSTATISTICS.
6070 *
6071 * @subsection NLPIGETSOLSTAT
6072 *
6073 * The NLPIGETSOLSTAT callback can be used to request the solution status (solved, infeasible, ...) after an NLP has been solved.
6074 *
6075 * @subsection NLPIGETTERMSTAT
6076 *
6077 * The NLPIGETTERMSTAT callback can be used to request the termination reason (normal, iteration limit, ...) after an NLP has been solved.
6078 *
6079 * @subsection NLPIGETSOLUTION
6080 *
6081 * The NLPIGETSOLUTION callback can be used to request the primal and dual solution values after an NLP solve.
6082 * The method should pass pointers to arrays of variable values to the caller.
6083 * 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.
6084 *
6085 * @subsection NLPIGETSTATISTICS
6086 *
6087 * The NLPIGETSTATISTICS callback can be used to request the statistical values (number of iterations, time, ...) after an NLP solve.
6088 * The method should fill the provided NLPSTATISTICS data structure.
6089 *
6090 * @section NLPI_ADDITIONALCALLBACKS Additional Callback Methods of an NLPI
6091 *
6092 * The additional callback methods do not need to be implemented in every case.
6093 *
6094 * @subsection NLPICOPY
6095 *
6096 * The NLPICOPY callback is executed if the plugin should be copied, e.g., when a SCIP instance is copied.
6097 *
6098 * It is advisable to implement this callback to make the NLP solver available in sub-SCIPs.
6099 * Note that the sub-NLP heuristic solves NLPs in a sub-SCIP.
6100 *
6101 * @subsection NLPIGETSOLVERPOINTER
6102 *
6103 * The NLPIGETSOLVERPOINTER callback can be used to pass a pointer to a solver specific data structure to the user.
6104 * Return NULL if you do not have a pointer to return.
6105 *
6106 * @subsection NLPIGETPROBLEMPOINTER
6107 *
6108 * The NLPIGETPROBLEMPOINTER callback can be used to pass a pointer to a solver specific data structure of the NLP to the user.
6109 *
6110 * @subsection NLPISETINITIALGUESS
6111 *
6112 * The NLPISETINITIALGUESS callback is executed to provide primal and dual initial values for the variables and constraints of an NLP.
6113 * 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.
6114 * 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).
6115 * In this case, the solver should clear previously set starting values and setup its own starting point.
6116 *
6117 */
6118
6119/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6120
6121/**@page EXPRINT How to add interfaces to expression interpreters
6122 *
6123 * An expression interpreter is a tool to compute point-wise the function values, gradients, and
6124 * Hessians of algebraic expressions which are given in the form of an expression.
6125 * Typically, this is done via automatic differentiation.
6126 * It is used, e.g., by an NLP solver interface to compute Jacobians and Hessians for the solver.
6127 *
6128 * The expression interpreter interface in SCIP has been implemented similar to those of the LP solver interface (LPI).
6129 * For one binary, exactly one expression interpreter has to be linked.
6130 * The expression interpreter API has been designed such that it can be used independently from a SCIP problem.
6131 *
6132 * A complete list of all expression interpreters contained in this release can be found \ref EXPRINTS "here".
6133 *
6134 * We now explain how users can add their own expression interpreters.
6135 * Take the interface to CppAD (\ref exprinterpret_cppad.cpp) as an example.
6136 * Unlike most other plugins, it is written in C++.
6137 *
6138 * Additional documentation for the callback methods of an expression interpreter, in particular for their input parameters,
6139 * can be found in the file \ref exprinterpret.h.
6140 *
6141 * Here is what you have to do to implement an expression interpreter:
6142 * -# Copy the file \ref exprinterpret_none.c into a file named "exprinterpret_myad.c".
6143 * Make sure to adjust your build system such that this file is compiled and linked to your project instead of exprinterpret implementations. \n
6144 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6145 * -# Open the new file with a text editor.
6146 * -# Define the expression interpreter data (see \ref EXPRINT_DATA).
6147 * -# Implement the interface methods (see \ref EXPRINT_INTERFACE).
6148 *
6149 *
6150 * @section EXPRINT_DATA Expression Interpreter Data
6151 *
6152 * In `struct SCIP_ExprInt`, you can store the general data of your expression interpreter.
6153 * For example, you could store the environment of your automatic differentiation code.
6154 *
6155 * @section EXPRINT_INTERFACE Interface Methods
6156 *
6157 * The expression interpreter has to implement a set of interface method.
6158 * In your "exprinterpret_myad.c", these methods are mostly dummy methods that return error codes.
6159 *
6160 * @subsection SCIPexprintGetName
6161 *
6162 * The SCIPexprintGetName() method should return the name of the expression interpreter.
6163 *
6164 * @subsection SCIPexprintGetDesc
6165 *
6166 * The SCIPexprintGetDesc() method should return a short description of the expression interpreter, e.g., the name of the developer of the code.
6167 *
6168 * @subsection SCIPexprintGetCapability
6169 *
6170 * The SCIPexprintGetCapability() method should return a bitmask that indicates the capabilities of the expression interpreter,
6171 * i.e., whether it can compute gradients and Hessians.
6172 *
6173 * @subsection SCIPexprintCreate
6174 *
6175 * The SCIPexprintCreate() method is called to create an expression interpreter data structure.
6176 * The method should initialize a `struct SCIP_ExprInt` here.
6177 *
6178 * @subsection SCIPexprintFree
6179 *
6180 * The SCIPexprintFree() method is called to free an expression interpreter data structure.
6181 * The method should free a `struct SCIP_ExprInt` here.
6182 *
6183 * @subsection SCIPexprintCompile
6184 *
6185 * The SCIPexprintCompile() method is called to initialize the data structures that are required to evaluate a particular expression.
6186 * The expression interpreter can create and return data that is particular to a given expression in the argument `exprintdata`.
6187 *
6188 * @subsection SCIPexprintFreeData
6189 *
6190 * The SCIPexprintFreeData() method is called to free the data that is particular to a given expression and was possibly created in SCIPexprintCompile().
6191 *
6192 * @subsection SCIPexprintGetExprCapability
6193 *
6194 * The SCIPexprintGetExprCapability() method is called to request the capability to evaluate a specific expression by the expression interpreter.
6195 *
6196 * In cases of user-given expressions, higher order derivatives may not be available for the user-expression,
6197 * even if the expression interpreter could handle these. This method allows to recognize that, e.g., the
6198 * Hessian for an expression is not available because it contains a user expression that does not provide
6199 * Hessians.
6200 *
6201 * @subsection SCIPexprintEval
6202 *
6203 * The SCIPexprintEval() method is called when the value of an expression should be computed for a point.
6204 *
6205 * @subsection SCIPexprintGrad
6206 *
6207 * The SCIPexprintGrad() method is called when the gradient of an expression represented by an expression should be computed for a point.
6208 *
6209 * @subsection SCIPexprintHessianSparsity
6210 *
6211 * The SCIPexprintHessianSparsity() method is called when the sparsity structure of the Hessian matrix should be computed and returned.
6212 * Only the position of nonzero entries in the lower-triangular part of Hessian should be reported.
6213 *
6214 * @subsection SCIPexprintHessian
6215 *
6216 * The SCIPexprintHessian() method is called when the Hessian of an expression should be computed for a point.
6217 */
6218
6219/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6220
6221/**@page TABLE How to add statistics tables
6222 *
6223 * After solving a constraint integer program, SCIP can display statistics tables with information about, e.g., the solving time,
6224 * number of nodes, LP iterations or the number of calls and successes of different plugins via "display statistics" in the shell
6225 * or via SCIPprintStatistics() in the C-interface. There already exists a wide variety of statistics tables which can be activated
6226 * or deactivated on demand, see src/scip/table_default.c. Additionally, the user can implement his/her own statistics tables
6227 * in order to display problem or algorithm specific values.
6228 * \n
6229 * A complete list of all statistics tables contained in this release can be found \ref TABLES "here".
6230 *
6231 * We now explain how users can add their own statistics tables.
6232 * We give the explanation for creating your own source file for each additional statistics table. Of course, you can collect
6233 * different additional statistics tables in one source file.
6234 * Take src/scip/table_default.c, where all default statistics tables are collected, as an example.
6235 * As all other default plugins, the default statistics table plugins and the statistics table template are written in C.
6236 * C++ users can easily adapt the code by using the scip::ObjTable wrapper base class and implement the scip_...() virtual methods
6237 * instead of the SCIP_DECL_TABLE... callback methods.
6238 *
6239 *
6240 * Additional documentation for the callback methods of a statistics table can be found in the file type_table.h.
6241 *
6242 * Here is what you have to do to implement a statistics table (assuming your statistics table is named "mystatisticstable"):
6243 * -# Copy the template files src/scip/table_xyz.c and src/scip/table_xyz.h into files named "table_mystatisticstable.c"
6244 * and "table_mystatisticstable.h".
6245 * \n
6246 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
6247 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6248 * -# Use SCIPincludeTableMystatisticstable() in order to include the statistics table into your SCIP instance,
6249 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
6250 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
6251 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mystatisticstable".
6252 * -# Adjust the \ref TABLE_PROPERTIES "properties of the statistics table".
6253 * -# Define the \ref TABLE_DATA "statistics table data". This is optional.
6254 * -# Implement the \ref TABLE_INTERFACE "interface methods".
6255 * -# Implement the \ref TABLE_FUNDAMENTALCALLBACKS "fundamental callback methods".
6256 * -# Implement the \ref TABLE_ADDITIONALCALLBACKS "additional callback methods". This is optional.
6257 *
6258 *
6259 * @section TABLE_PROPERTIES Properties of a Statistics Table
6260 *
6261 * At the top of the new file "table_mystatisticstable.c" you can find the statistics table properties.
6262 * These are given as compiler defines.
6263 * In the C++ wrapper class, you have to provide the statistics table properties by calling the constructor
6264 * of the abstract base class scip::ObjTable from within your constructor.
6265 * The properties you have to set have the following meaning:
6266 *
6267 * \par TABLE_NAME: the name of the statistics table.
6268 * This name is used in the interactive shell to address the statistics table.
6269 * Additionally, if you are searching for a statistics table with SCIPfindTable(), this name is looked up.
6270 * Names have to be unique: no two statistic tables may have the same name.
6271 *
6272 * \par TABLE_DESC: the description of the statistics table.
6273 * This string is printed as a description of the statistics table in the interactive shell.
6274 *
6275 * \par TABLE_POSITION: the position of the statistics table.
6276 * In the statistics output, the statistics tables will be ordered by increasing position. Compare with the
6277 * default statistics tables in "table_default.c" to find a value which will give you the desired position
6278 * between the default statistics tables. If you give your table a negative position value, it will appear
6279 * before all SCIP statistcs, with a value larger than 20000 it will appear after all default statistics.
6280 *
6281 * \par TABLE_EARLIEST_STAGE: output of the statistics table is only printed from this stage onwards
6282 * The output routine of your statistics table will only be called if SCIP has reached this stage. For
6283 * example, the default table "tree" will only output information starting from SCIP_STAGE_SOLVING, because
6284 * there is no meaningful information available before, while the "presolver" table can already be called
6285 * in SCIP_STAGE_TRANSFORMED.
6286 *
6287 * @section TABLE_DATA Statistics Table Data
6288 *
6289 * Below the header "Data structures" you can find a struct which is called "struct SCIP_TableData".
6290 * In this data structure, you can store the data of your statistics table. For example, you should store the adjustable
6291 * parameters of the statistics table in this data structure.
6292 * If you are using C++, you can add statistics table data as usual as object variables to your class.
6293 * \n
6294 * Defining statistics table data is optional. You can leave the struct empty.
6295 *
6296 *
6297 * @section TABLE_INTERFACE Interface Methods
6298 *
6299 * At the bottom of "table_mystatisticstable.c" you can find the interface method SCIPincludeTableMystatisticstable(), which also
6300 * appears in "table_mystatisticstable.h".
6301 * \n
6302 * This method only has to be adjusted slightly.
6303 * It is responsible for notifying SCIP of the presence of the statistics table by calling the method
6304 * SCIPincludeTable().
6305 *
6306 * 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
6307 * application.
6308 *
6309 * If you are using statistics table data, you have to allocate the memory for the data at this point.
6310 * You can do this by calling:
6311 * \code
6312 * SCIP_CALL( SCIPallocBlockMemory(scip, &tabledata) );
6313 * \endcode
6314 * You also have to initialize the fields in struct SCIP_TableData afterwards.
6315 *
6316 * Although this is very uncommon, you may also add user parameters for your statistics table, see the method
6317 * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
6318 *
6319 *
6320 * @section TABLE_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Statistics Table
6321 *
6322 * Statistics table plugins have only one fundamental callback method, namely the \ref TABLEOUTPUT method.
6323 * This method has to be implemented for every display column; the other callback methods are optional.
6324 * In the C++ wrapper class scip::ObjTable, the scip_output() method (which corresponds to the \ref TABLEOUTPUT callback) is a virtual
6325 * abstract member function.
6326 * You have to implement it in order to be able to construct an object of your statistics table class.
6327 *
6328 * Additional documentation for the callback methods can be found in type_table.h.
6329 *
6330 * @subsection TABLEOUTPUT
6331 *
6332 * The TABLEOUTPUT callback is called whenever SCIP is asked to print statistics (because the user typed "display statistics"
6333 * in the shell or called SCIPprintStatistics()). In this callback, the table should print all of its information to the given file
6334 * (which may be NULL if the output should be printed to the console).
6335 *
6336 * Typical methods called by a statistics table are, for example, SCIPdispLongint(), SCIPdispInt(), SCIPdispTime(), and
6337 * SCIPinfoMessage().
6338 *
6339 *
6340 * @section TABLE_ADDITIONALCALLBACKS Additional Callback Methods of a Statistics Table
6341 *
6342 * The additional callback methods do not need to be implemented in every case.
6343 * They can be used, for example, to initialize and free private data.
6344 *
6345 * @subsection TABLECOPY
6346 *
6347 * The TABLECOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this callback
6348 * as <code>NULL</code> the user disables the execution of the specified column. In general it is probably not needed to
6349 * implement that callback since the output of the copied instance is usually suppressed. In the other case or for
6350 * debugging the callback should be implement.
6351 *
6352 *
6353 * @subsection TABLEFREE
6354 *
6355 * If you are using statistics table data, you have to implement this method in order to free the statistics table data.
6356 * This can be done by the following procedure:
6357 * @refsnippet{tests/src/misc/snippets.c,SnippetTableFree}
6358 *
6359 * If you have allocated memory for fields in your statistics table data, remember to free this memory
6360 * before freeing the statistics table data itself.
6361 * If you are using the C++ wrapper class, this method is not available.
6362 * Instead, just use the destructor of your class to free the member variables of your class.
6363 *
6364 * @subsection TABLEINIT
6365 *
6366 * The TABLEINIT callback is executed after the problem is transformed.
6367 * The statistics table may, e.g., use this call to initialize its statistics table data.
6368 *
6369 * @subsection TABLEEXIT
6370 *
6371 * The TABLEEXIT callback is executed before the transformed problem is freed.
6372 * In this method, the statistics table should free all resources that have been allocated for the solving process in
6373 * \ref TABLEINIT.
6374 *
6375 * @subsection TABLEINITSOL
6376 *
6377 * The TABLEINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
6378 * begin. The statistics table may use this call to initialize its branch-and-bound specific data.
6379 *
6380 * @subsection TABLEEXITSOL
6381 *
6382 * The TABLEEXITSOL callback is executed before the branch-and-bound process is freed. The statistics table should use this
6383 * call to clean up its branch-and-bound specific data.
6384 */
6385
6386/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6387
6388/**@page BENDER How to add custom Benders' decomposition implementations
6389 *
6390 * Benders' decomposition is a very popular mathematical programming technique that is applied to solve structured
6391 * problems. Problems that display a block diagonal structure are particularly amenable to the application of Benders'
6392 * decomposition. Such problems are given by
6393 *
6394 * \f[
6395 * \begin{array}[t]{rllclcl}
6396 * \min & \displaystyle & c^{T}x & + & d^{T}y \\
6397 * & \\
6398 * subject \ to & \displaystyle & Ax & & & = & b \\
6399 * & \\
6400 * & \displaystyle & Tx & + & Hy & = & h \\
6401 * & \\
6402 * & & x & & & \in & \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
6403 * & & & & y & \in & \mathbb{R}^{m} \\
6404 * \end{array}
6405 * \f]
6406 *
6407 * The variables \f$x\f$ and \f$y\f$ are described as the first and second stage variables respectively. In the
6408 * classical use of Benders' decomposition, it is a requirement that the all second stage variables are continuous.
6409 * Extensions to the classical Benders' decomposition approach have permitted the use of more general second stage
6410 * problems.
6411 *
6412 * The application of Benders' decomposition to the above problem results in a subproblem, given by
6413 *
6414 * \f[
6415 * \begin{array}[t]{rll}
6416 * \min & \displaystyle & d^{T}y \\
6417 * & \\
6418 * subject \ to & \displaystyle & Hy = h - T\bar{x} \\
6419 * & \\
6420 * & & y \in \mathbb{R}^{m} \\
6421 * \end{array}
6422 * \f]
6423 *
6424 * where \f$\bar{x}\f$ is a solution vector of the first stage variables. As such, the subproblem is a problem only in
6425 * \f$y\f$. The dual solution to the subproblem, either an extreme point or extreme ray, is used to generate cuts that
6426 * are added to the master problem. Let \f$\lambda\f$ be the vector of dual variables associated with the set of
6427 * constraints from the subproblem. If, for a given \f$\bar{x}\f$, the subproblem is infeasible, then \f$\lambda\f$
6428 * corresponds to a dual ray and is used to produce the cut
6429 *
6430 * \f[
6431 * 0 \geq \lambda(h - Tx)
6432 * \f]
6433 *
6434 * which eliminates \f$\bar{x}\f$ from the master problem. If, for a given \f$\bar{x}\f$, the subproblem is feasible,
6435 * then \f$\lambda\f$ corresponds to a dual extreme point and is used to produce the cut
6436 *
6437 * \f[
6438 * \varphi \geq \lambda(h - Tx)
6439 * \f]
6440 *
6441 * where \f$\varphi\f$ is an auxiliary variable added to the master problem as an underestimator of the optimal
6442 * subproblem objective function value.
6443 *
6444 * Given \f$\Omega^{p}\f$ and \f$\Omega^{r}\f$ as the sets of dual extreme points and rays of the subproblem,
6445 * respectively, the Benders' decomposition master problem is given by
6446 *
6447 * \f[
6448 * \begin{array}[t]{rll}
6449 * \min & \displaystyle & c^{T}x + \varphi \\
6450 * & \\
6451 * subject \ to & \displaystyle & Ax = b \\
6452 * & \\
6453 * & \displaystyle & \varphi \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r}\\
6454 * & \\
6455 * & \displaystyle & 0 \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r} \\
6456 * & \\
6457 * & & x \in \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
6458 * & & \varphi \in \mathbb{R} \\
6459 * \end{array}
6460 * \f]
6461 *
6462 * The Benders' decomposition framework of SCIP allows the user to provide a custom implementation of many aspects of
6463 * the Benders' decomposition algorithm. It is possible to implement multiple Benders' decompositions that work in
6464 * conjunction with each other. Such a situation is where you may have different formulations of the Benders'
6465 * decomposition subproblem.
6466 *
6467 * The current list of all Benders' decomposition implementations available in this release can be found \ref BENDERS
6468 * "here".
6469 *
6470 * We now explain how users can add their own Benders' decomposition implementations.
6471 * Take the default Benders' decomposition implementation (src/scip/benders_default.c) as an example. Same as all other
6472 * default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjBenders wrapper base
6473 * class and implement the scip_...() virtual methods instead of the SCIP_DECL_BENDERS... callback methods.
6474 *
6475 * Additional documentation for the callback methods of a Benders' decomposition implementation, in particular for the
6476 * input parameters, can be found in the file type_benders.h.
6477 *
6478 * Here is what you have to do to implement a custom Benders' decomposition:
6479 * -# Copy the template files src/scip/benders_xyz.c and src/scip/benders_xyz.h into files "benders_mybenders.c" and
6480 * "benders_mybenders.h".
6481 \n
6482 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
6483 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6484 * -# Use SCIPincludeBendersMybenders() in order to include the Benders' decomposition into your SCIP instance, e.g., in
6485 * the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
6486 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
6487 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mybenders".
6488 * -# Adjust the properties of the Benders' decomposition (see \ref BENDERS_PROPERTIES).
6489 * -# Define the Benders' decomposition data (see \ref BENDERS_DATA). This is optional.
6490 * -# Implement the interface methods (see \ref BENDERS_INTERFACE).
6491 * -# Implement the fundamental callback methods (see \ref BENDERS_FUNDAMENTALCALLBACKS).
6492 * -# Implement the additional callback methods (see \ref BENDERS_ADDITIONALCALLBACKS). This is optional.
6493 *
6494 *
6495 * @section BENDERS_PROPERTIES Properties of a Benders' decomposition
6496 *
6497 * At the top of the new file "benders_mybenders.c", you can find the Benders' decomposition properties.
6498 * These are given as compiler defines.
6499 * In the C++ wrapper class, you have to provide the Benders' decomposition properties by calling the constructor
6500 * of the abstract base class scip::ObjBenders from within your constructor.
6501 * The properties you have to set have the following meaning:
6502 *
6503 * \par BENDERS_NAME: the name of the Benders' decomposition.
6504 * This name is used in the interactive shell to address the Benders' decomposition.
6505 * Additionally, if you are searching for a Benders' decomposition with SCIPfindBenders(), this name is looked up.
6506 * Names have to be unique: no two Benders' decompositions may have the same name.
6507 *
6508 * \par BENDERS_DESC: the description of the Benders' decomposition.
6509 * This string is printed as a description of the Benders' decomposition in the interactive shell.
6510 *
6511 * \par BENDERS_PRIORITY: the priority of the Benders' decomposition.
6512 * During the enforcement and checking of solutions in src/scip/cons_benders.c and src/scip/cons_benderslp.c, every
6513 * active Benders' decompositions are called. The execution method of the Benders' decomposition calls each of the
6514 * subproblems and generates cuts from their solutions. So the active Benders' decompositions are called in order of
6515 * priority until a cut is generated or feasibility is proven.
6516 * \n
6517 * The priority of the Benders' decomposition should be set according to the difficulty of solving the subproblems and
6518 * the generation of cuts. However, it is possible to prioritise the Benders' decompositions with respect to the
6519 * strength of the subproblem formulation and the resulting cuts.
6520 *
6521 * \par BENDERS_CUTLP: should Benders' decomposition cuts be generated during the enforcement of LP solutions.
6522 * This is a flag that is used by src/scip/cons_benders.c and src/scip/cons_benderslp.c to idicate whether the
6523 * enforcement of LP solutions should involve solving the Benders' decomposition subproblems. This should be set to TRUE
6524 * to have an exact solution algorithm. In the presence of multiple Benders' decomposition, it may be desired to enforce
6525 * the LP solutions for only a subset of those implemented.
6526 *
6527 * \par BENDERS_CUTRELAX: should Benders' decomposition cuts be generated during the enforcement of relaxation solutions.
6528 * This is a flag that is used by src/scip/cons_benders.c and src/scip/cons_benderslp.c to idicate whether the
6529 * enforcement of relaxation solutions should involve solving the Benders' decomposition subproblems. This should be
6530 * set to TRUE to have an exact solution algorithm. In the presence of multiple Benders' decomposition, it may be desired
6531 * to enforce the relaxation solutions for only a subset of those implemented. This parameter will only take effect if
6532 * external relaxation have been implemented.
6533 *
6534 * \par BENDERS_CUTPSEUDO: should Benders' decomposition subproblems be solved during the enforcement of pseudo solutions.
6535 * This is a flag that is used by src/scip/cons_benders.c and src/scip/cons_benderslp.c to indicate whether the
6536 * enforcement of pseudo solutions should involve solving the Benders' decomposition subproblems. This should be set to
6537 * TRUE, since not enforcing pseudo solutions could result in an error or suboptimal result. During the enforcement of
6538 * pseudo solutions, no cuts are generated. Only a flag to indicate whether the solution is feasible or if the LP should
6539 * be solved again is returned.
6540 *
6541 * \par BENDERS_SHAREAUXVARS: should this Benders' decomposition use the auxiliary variables from the highest priority
6542 * Benders' decomposition.
6543 * This parameter only takes effect if multiple Benders' decompositions are implemented. Consider the case that two Benders'
6544 * decompositions are implemented with different formulations of the subproblem. Since the subproblems in each of the
6545 * decomposition will have the same optimal solution, then it is useful to only have a single auxiliary variable for the
6546 * two different subproblems. This means that when an optimality cut is generated in the lower priority Benders'
6547 * decomposition, the auxiliary variable from the highest priority Benders' decomposition will be added to the right
6548 * hand side.
6549 *
6550 * @section BENDERS_DATA Benders' decomposition Data
6551 *
6552 * Below the header "Data structures" you can find a struct which is called "struct SCIP_BendersData".
6553 * In this data structure, you can store the data of your Benders' decomposition. For example, you should store the adjustable
6554 * parameters of the Benders' decomposition in this data structure. In a Benders' decomposition, user parameters for the
6555 * number of subproblems and an array to store the subproblem SCIP instances could be useful.
6556 * \n
6557 * Defining Benders' decomposition data is optional. You can leave the struct empty.
6558 *
6559 * @section BENDERS_INTERFACE Interface Methods
6560 *
6561 * At the bottom of "benders_mybenders.c", you can find the interface method SCIPincludeBendersMybenders(),
6562 * which also appears in "benders_mybenders.h"
6563 * SCIPincludeBendersMybenders() is called by the user, if (s)he wants to include the Benders' decomposition,
6564 * i.e., if (s)he wants to use the Benders' decomposition in his/her application.
6565 *
6566 * This method only has to be adjusted slightly.
6567 * It is responsible for notifying SCIP of the presence of the Benders' decomposition. For this, you can either call SCIPincludeBenders(),
6568 * or SCIPincludeBendersBasic() since SCIP version 3.0. In the latter variant, \ref BENDERS_ADDITIONALCALLBACKS "additional callbacks"
6569 * must be added via setter functions as, e.g., SCIPsetBendersCopy(). We recommend this latter variant because
6570 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
6571 * variant must be manually adjusted with every SCIP release containing new callbacks for Benders' decompositions in order to compile.
6572 *
6573 * If you are using Benders' decomposition data, you have to allocate the memory
6574 * for the data at this point. You can do this by calling:
6575 * \code
6576 * SCIP_CALL( SCIPallocBlockMemory(scip, &bendersdata) );
6577 * \endcode
6578 * You also have to initialize the fields in "struct SCIP_BendersData" afterwards. For freeing the
6579 * Benders' decomposition data, see \ref BENDERSFREE.
6580 *
6581 * You may also add user parameters for your Benders' decomposition, see \ref PARAM for how to add user parameters and
6582 * the method SCIPincludeBendersDefault() in src/scip/benders_default.c for an example.
6583 *
6584 * It is advised to disable presolving for the Benders' decomposition master problem by calling SCIPsetPresolving() with
6585 * the parameter SCIP_PARAMSETTING_OFF. Presolving should be disabled because reductions on the master problem could be
6586 * invalid since constraints have been transferred to the subproblems. It is not necessary to disable all presolving,
6587 * but care must be taken when it is used for the Benders' decomposition master problem.
6588 *
6589 * The Benders' decomposition constraint handler, see src/scip/cons_benders.c, includes a presolver for tightening the
6590 * bound on the auxiliary variables. This presolver can be enabled with by setting "presolving/maxround" to 1 and
6591 * "constraints/benders/maxprerounds" to 1. This presolver solves the Benders' decomposition subproblems without fixing
6592 * the master problem variables to find a lower bound for the auxiliary variable.
6593 *
6594 *
6595 * @section BENDERS_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Benders' decomposition
6596 *
6597 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
6598 * an operational algorithm.
6599 * They are passed together with the Benders' decomposition itself to SCIP using SCIPincludeBenders() or SCIPincludeBendersBasic(),
6600 * see @ref BENDERS_INTERFACE.
6601 *
6602 * Benders' decomposition plugins have two callbacks, @ref BENDERSGETVAR and @ref BENDERSCREATESUB that must be implemented.
6603 *
6604 * Additional documentation for the callback methods, in particular to their input parameters,
6605 * can be found in type_benders.h.
6606 *
6607 * @subsection BENDERSGETVAR
6608 *
6609 * The BENDERSGETVAR callback provides a mapping between the master problem variables and their corresponding subproblem
6610 * variables, and vice versa. The parameters of this function include the variable for which the mapped variable is
6611 * desired and the problem number for the mapped variable. When requesting a subproblem variable for a given master
6612 * problem variable, the master variable is input with the appropriate subproblem index. If a master problem variable is
6613 * requested for a given subproblem variable, then the subproblem variable is input with the subproblem index given as
6614 * -1.
6615 *
6616 * An example of how to implement the mapping between the master and subproblem variables is shown by
6617 *
6618 * @refsnippet{src/scip/benders_default.c,SnippetBendersGetvarDefault}
6619 *
6620 * In the above code snippet, the hashmaps providing the mapping between the master and subproblem variables are
6621 * constructed in the <code>SCIP_STAGE_INIT</code> stage (see \ref BENDERSINIT).
6622 *
6623 * The requested variable is returned via the mappedvar parameter. There may not exist a corresponding master
6624 * (subproblem) variable for every input subproblem (master) variable. In such cases were no corresponding variable
6625 * exists, mappedvar must be returned as NULL.
6626 *
6627 * The mapped variables are retrieved by calling SCIPgetBendersMasterVar() and SCIPgetBendersSubproblemVar().
6628 *
6629 * The variable mapping must be created before <code>SCIP_STAGE_PRESOLVE</code> stage. This is because the variable
6630 * mapping is required for checking solutions found by heuristics during presolving.
6631 *
6632 * @subsection BENDERSCREATESUB
6633 *
6634 * The BENDERSCREATESUB callback is executed during the <code>SCIP_STAGE_INIT</code> stage. In this function, the
6635 * user must register the SCIP instances for each subproblem. The BENDERSCREATESUB callback is executed once for each
6636 * subproblem. The user registers a subproblem by calling SCIPbendersAddSubproblem().
6637 *
6638 * It is possible to build the SCIP instance for the subproblem during the execution of this callback. However, it may
6639 * be more convenient to build the subproblem instances during the problem creation stage of the master problem and
6640 * store the subproblem SCIP instances in SCIP_BendersData. This approach is used in src/scip/benders_default.c.
6641 *
6642 * @section BENDERS_ADDITIONALCALLBACKS Additional Callback Methods of a Benders' decomposition implementation
6643 *
6644 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
6645 * implemented for most applications, they can be used, for example, to initialize and free private data.
6646 * Additional callbacks can either be passed directly with SCIPincludeBenders() to SCIP or via specific
6647 * <b>setter functions</b> after a call of SCIPincludeBendersBasic(), see also @ref BENDERS_INTERFACE.
6648 *
6649 * @subsection BENDERSFREE
6650 *
6651 * If you are using Benders' decomposition data (see \ref BENDERS_DATA and \ref BENDERS_INTERFACE), you have to
6652 * implement this method in order to free the Benders' decomposition data. This can be done by the following procedure:
6653 *
6654 * @refsnippet{src/scip/benders_default.c,SnippetBendersFreeDefault}
6655 *
6656 * If you have allocated memory for fields in your Benders' decomposition data, remember to free this memory
6657 * before freeing the Benders' decomposition data itself.
6658 * If you are using the C++ wrapper class, this method is not available.
6659 * Instead, just use the destructor of your class to free the member variables of your class.
6660 *
6661 * @subsection BENDERSCOPY
6662 *
6663 * The BENDERSCOPY callback is executed when a SCIP instance is copied, e.g. to
6664 * solve a sub-SCIP. By
6665 * defining this callback as
6666 * <code>NULL</code> the user disables the execution of the specified
6667 * separator for all copied SCIP instances. This may deteriorate the performance
6668 * of primal heuristics using sub-SCIPs.
6669 *
6670 * If a user wishes to employ the Large Neighbourhood Benders' Search, it is necessary for the BENDERSCOPY callback to
6671 * be implemented. This is required because the sub-SCIP instances of large neighbourhood search heuristics can only
6672 * access the implemented Benders' decomposition if it is copied via the BENDERSCOPY callback.
6673 *
6674 * @subsection BENDERSINIT
6675 *
6676 * The BENDERSINIT callback is executed after the problem is transformed.
6677 * The Benders' decomposition implementation may, e.g., use this call to initialize its Benders' decomposition data. In
6678 * src/scip/benders_default.c BENDERSINIT is used to create the mapping between the master and subproblem variables.
6679 * The difference between the original and the transformed problem is explained in
6680 * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
6681 *
6682 * @subsection BENDERSEXIT
6683 *
6684 * The BENDERSEXIT callback is executed before the transformed problem is freed.
6685 * In this method, the Benders' decomposition implementation should free all resources that have been allocated for
6686 * the solving process in BENDERSINIT.
6687 *
6688 * @subsection BENDERSINITPRE
6689 *
6690 * The BENDERSINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
6691 * The Benders' decomposition may use this call to initialize its presolving data before the presolving process begins.
6692 *
6693 * @subsection BENDERSEXITPRE
6694 *
6695 * The BENDERSEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
6696 * The Benders' decomposition implementation may use this call, e.g., to clean up its presolving data.
6697 * Besides clean up, no time consuming operations should be done.
6698 *
6699 * @subsection BENDERSINITSOL
6700 *
6701 * The BENDERSINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
6702 * begin. The Benders' decomposition implementation may use this call to initialize its branch-and-bound specific data.
6703 *
6704 * @subsection BENDERSEXITSOL
6705 *
6706 * The BENDERSEXITSOL callback is executed before the branch-and-bound process is freed. The Benders' decomposition
6707 * implementation should use this call to clean up its branch-and-bound data.
6708 *
6709 * @subsection BENDERSPRESUBSOLVE
6710 *
6711 * The BENDERSPRESUBSOLVE callback is provided to give the user an opportunity in each iteration to perform any setup
6712 * operations prior to solving the subproblems. This callback also allows the user to skip the subproblem solve for the
6713 * current iteration. In this case, the user must set the result parameter appropriately
6714 * - the subproblem was not solved in this iteration. Other decompositions will be checked (SCIP_DIDNOTRUN).
6715 * - a constraint has been added to the master problem. No other decompositions will be checked (SCIP_CONSADDED).
6716 * - a cut has been added to the master problem. No other decompositions will be checked (SCIP_SEPARATED).
6717 * - feasibility of the solution is reported to SCIP. Other decompositions will be checked (SCIP_FEASIBLE).
6718 * - infeasibility of the solution is reported to SCIP. No other decompositions will be checked (SCIP_INFEASIBLE).
6719 *
6720 * @subsection BENDERSSOLVESUBCONVEX
6721 *
6722 * Two different subproblem solving functions are provide in the Benders' decomposition framework, BENDERSSOLVESUBCONVEX
6723 * and BENDERSSOLVESUB. These two solving functions are used in the two solving loops of the Benders' decomposition
6724 * framework. The first solving loop solves convex subproblems and convex relaxations of CIPs. The BENDERSSOLVESUBCONVEX
6725 * callback is executed only during the FIRST solving loop. Benders' cut generating methods suitable for convex
6726 * subproblems are executed during this solving loop. If a cut is found, then the second solve loop is not executed. If
6727 * your decomposition does not have any convex subproblems, then it is not necessary to implement the
6728 * BENDERSSOLVESUBCONVEX callback. However, it may be computationally beneficial to solve the convex relaxation of CIP
6729 * subproblems, such as the LP relaxation of a MIP subproblem.
6730 *
6731 * The second solve loop expects that the CIP subproblems are solved to optimality.
6732 *
6733 * If you implement the BENDERSSOLVESUBCONVEX callback, it is necessary to implement the BENDERSFREESUB callback.
6734 *
6735 * The objective function value after the subproblem solve and the result must be returned. The permissible results
6736 * are:
6737 * - the subproblem was not solved in this iteration (SCIP_DIDNOTRUN)
6738 * - the subproblem is solved and is feasible (SCIP_FEASIBLE)
6739 * - the subproblem is solved and is infeasible (SCIP_INFEASIBLE)
6740 * - the subproblem is solved and is unbounded (SCIP_UNBOUNDED)
6741 *
6742 * @subsection BENDERSSOLVESUB
6743 *
6744 * The BENDERSSOLVESUB is executed only during the SECOND solve loop. This callback function is used to solve CIP
6745 * subproblems. If your decomposition does not have any CIP subproblems, then it is not necessary to implement the
6746 * BENDERSSOLVESUB callback.
6747 *
6748 * If you implement the BENDERSSOLVESUB callback, it is necessary to implement the BENDERSFREESUB callback.
6749 *
6750 * The objective function value after the subproblem solve and the result must be returned. The permissible results
6751 * are:
6752 * - the subproblem was not solved in this iteration (SCIP_DIDNOTRUN)
6753 * - the subproblem is solved and is feasible (SCIP_FEASIBLE)
6754 * - the subproblem is solved and is infeasible (SCIP_INFEASIBLE)
6755 * - the subproblem is solved and is unbounded (SCIP_UNBOUNDED)
6756 *
6757 * @subsection BENDERSPOSTSOLVE
6758 *
6759 * The BENDERSPOSTSOLVE callback is executed after the subproblems have been solved and any required cuts have been
6760 * generated, but before the subproblems are freed. This callback provides the user an opportunity to interact the
6761 * subproblems at a global level. For example, the user is able to construct a solution to the original problem by
6762 * combining the solutions from the master problem and all subproblems.
6763 *
6764 * Additionally, the user is able to merge subproblems into the master problem during the execution of this callback.
6765 * The merging of subproblems into the master problem could be desired if it is too time consuming to satisfy the
6766 * feasibility of a subproblem or the appropriate cutting methods are not available for the provided subproblem. A list
6767 * of indicies of subproblems suitable for merging are given in the mergecands array. The first npriomergecands are the
6768 * merge candidates that must be merged into the master problem. If they are not, then the solution process will
6769 * terminate with an error. These merge candidates arise if a cut could not be generated due to numerical difficulties.
6770 * The remaining nmergecands - npriomergecands are subproblems that could be merged into the master problem if desired
6771 * by the user.
6772 *
6773 * @subsection BENDERSFREESUB
6774 *
6775 * The BENDERSFREESUB callback is executed to clean up the subproblems after the solving process and prepare them for
6776 * the next iteration. Typically, SCIPfreeTransform() is called for each subproblem to free the transformed problem.
6777 *
6778 */
6779
6780/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6781
6782/**@page BENDERSCUT How to add custom Benders' decomposition cut generation methods
6783 *
6784 * The Benders' decomposition framework of SCIP allows the user to provide a custom implementation of cut generation
6785 * methods. The Benders' decomposition cut methods are linked to the Benders' decomposition implementations, not the
6786 * master problem SCIP instance. As such, you are able to have different Benders' decomposition cut methods for each
6787 * included Benders' decomposition.
6788 * The current list of all Benders' decomposition cut generation methods available in this release can be found
6789 * \ref BENDERSCUTS "here".
6790 *
6791 * We now explain how users can add their own Benders' decomposition cut methods. Take the default Benders'
6792 * decomposition cut method (src/scip/benderscut_opt.c) as an example. This Benders' decomposition cut method generates
6793 * a classical optimality cut from the optimal dual solution to the convex relaxation of the Benders' decomposition
6794 * subproblem. Same as all other default plugins, it is written in C. C++ users can easily adapt the code by using the
6795 * scip::ObjBenderscut wrapper base class and implement the scip_...() virtual methods instead of the
6796 * SCIP_DECL_BENDERSCUT... callback methods.
6797 *
6798 * Additional documentation for the callback methods of a Benders' decomposition cut methods, in particular for the
6799 * input parameters, can be found in the file type_benderscut.h.
6800 *
6801 * Here is what you have to do to implement a custom Benders' decomposition cut method:
6802 * -# Copy the template files src/scip/benderscut_xyz.c and src/scip/benderscut_xyz.h into files "benderscut_mybenderscut.c" and
6803 * "benderscut_mybenderscut.h".
6804 \n
6805 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
6806 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6807 * -# Use SCIPincludeBenderscutMybenderscut() in order to include the Benders' decomposition cut method into your SCIP
6808 * instance, e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
6809 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
6810 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mybenderscut".
6811 * -# Adjust the properties of the Benders' decomposition (see \ref BENDERSCUT_PROPERTIES).
6812 * -# Define the Benders' decomposition data (see \ref BENDERSCUT_DATA). This is optional.
6813 * -# Implement the interface methods (see \ref BENDERSCUT_INTERFACE).
6814 * -# Implement the fundamental callback methods (see \ref BENDERSCUT_FUNDAMENTALCALLBACKS).
6815 * -# Implement the additional callback methods (see \ref BENDERSCUT_ADDITIONALCALLBACKS). This is optional.
6816 *
6817 *
6818 * @section BENDERSCUT_PROPERTIES Properties of a Benders' decomposition
6819 *
6820 * At the top of the new file "benderscut_mybenderscut.c", you can find the Benders' decomposition cut methods
6821 * properties. These are given as compiler defines.
6822 * In the C++ wrapper class, you have to provide the Benders' decomposition properties by calling the constructor
6823 * of the abstract base class scip::ObjBenderscut from within your constructor.
6824 * The properties you have to set have the following meaning:
6825 *
6826 * \par BENDERSCUT_NAME: the name of the Benders' decomposition cut method.
6827 * This name is used in the interactive shell to address the Benders' decomposition cut method.
6828 * Additionally, if you are searching for a Benders' decomposition cut method with SCIPfindBenderscut(), this name is
6829 * looked up. Names have to be unique: no two Benders' decomposition cut methods linked to the same Benders'
6830 * decomposition may have the same name.
6831 *
6832 * \par BENDERSCUT_DESC: the description of the Benders' decomposition cut method.
6833 * This string is printed as a description of the Benders' decomposition cut method in the interactive shell.
6834 *
6835 * \par BENDERSCUT_PRIORITY: the priority of the Benders' decomposition cut method.
6836 * In each of the Benders' decomposition subproblem solving loops, the included Benders' decomposition cut methods are
6837 * called in order of priority. The priority is important because once a cut is generated for a subproblem, no other
6838 * cuts are generated for that subproblem for that solving loop.
6839 * \n
6840 * The priority of the Benders' decomposition should be set according to the order in which the cut should be generated.
6841 * For example, the priority of the included cuts attempt to generation feasibility cuts (src/scip/benderscut_feas.c
6842 * and src/scip/benderscut_nogood.c) prior to attempting to generate optimality cuts.
6843 *
6844 * \par BENDERSCUT_LPCUT: Can this cut be applied to convex subproblems and convex relaxations of CIP subproblems?
6845 * Since the Benders' decomposition framework executes two different solving loops, one for convex subproblems and the
6846 * other for CIP subproblems, the Benders' decomposition cut methods must be partitioned by their suitability for each
6847 * subproblem type. If BENDERSCUT_LPCUT is set to TRUE, then this cut is only applied to convex subproblems and convex
6848 * relaxations of CIP subproblems.
6849 *
6850 * @section BENDERSCUT_DATA Benders' decomposition Data
6851 *
6852 * Below the header "Data structures" you can find a struct which is called "struct SCIP_BenderscutData".
6853 * In this data structure, you can store the data of your Benders' decomposition. For example, you should store the adjustable
6854 * parameters of the Benders' decomposition in this data structure. In a Benders' decomposition, user parameters for the
6855 * number of subproblems and an array to store the subproblem SCIP instances could be useful.
6856 * \n
6857 * Defining Benders' decomposition data is optional. You can leave the struct empty.
6858 *
6859 * @section BENDERSCUT_INTERFACE Interface Methods
6860 *
6861 * At the bottom of "benderscut_mybenderscut.c", you can find the interface method SCIPincludeBenderscutMybenderscut(),
6862 * which also appears in "benderscut_mybenderscut.h"
6863 * SCIPincludeBenderscutMybenderscut() is called by the user, if (s)he wants to include the Benders' decomposition,
6864 * i.e., if (s)he wants to use the Benders' decomposition in his/her application.
6865 *
6866 * This method only has to be adjusted slightly.
6867 * It is responsible for notifying SCIP of the presence of the Benders' decomposition. For this, you can either call SCIPincludeBenderscut(),
6868 * or SCIPincludeBenderscutBasic() since SCIP version 3.0. In the latter variant, \ref BENDERSCUT_ADDITIONALCALLBACKS "additional callbacks"
6869 * must be added via setter functions as, e.g., SCIPsetBenderscutCopy(). We recommend this latter variant because
6870 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
6871 * variant must be manually adjusted with every SCIP release containing new callbacks for Benders' decompositions in order to compile.
6872 *
6873 * If you are using Benders' decomposition cut data, you have to allocate the memory
6874 * for the data at this point. You can do this by calling:
6875 * \code
6876 * SCIP_CALL( SCIPallocBlockMemory(scip, &benderscutdata) );
6877 * \endcode
6878 * You also have to initialize the fields in "struct SCIP_BenderscutData" afterwards. For freeing the
6879 * Benders' decomposition cut data, see \ref BENDERSCUTFREE.
6880 *
6881 * You may also add user parameters for your Benders' decomposition, see \ref PARAM for how to add user parameters and
6882 * the method SCIPincludeBenderscutOpt() in src/scip/benderscut_opt.c for an example.
6883 *
6884 *
6885 * @section BENDERSCUT_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Benders' decomposition cut method
6886 *
6887 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
6888 * an operational algorithm.
6889 * They are passed together with the Benders' decomposition itself to SCIP using SCIPincludeBenderscut() or SCIPincludeBenderscutBasic(),
6890 * see @ref BENDERSCUT_INTERFACE.
6891 *
6892 * Benders' decomposition cut methods only one callback, @ref BENDERSCUTEXEC, that must be implemented.
6893 *
6894 * Additional documentation for the callback methods, in particular to their input parameters,
6895 * can be found in type_benderscut.h.
6896 *
6897 * @subsection BENDERSCUTEXEC
6898 *
6899 * The BENDERSCUTEXEC callback is called during the cut generation process within the Benders' decomposition subproblem
6900 * solving loop. This method must generate a cut for the given subproblem if the associated subsystem is not optimal
6901 * with respect to the checked master problem solution.
6902 *
6903 * When generating cuts, it is possible to store these within the SCIP_BendersData of the associated Benders'
6904 * decomposition. This is achieved by calling SCIPstoreBenderscutCons() (SCIPstoreBenderscutCut() if the Benders'
6905 * decomposition cut is added as a cutting plane instead as a constraint). The storing of cuts can be useful when using
6906 * the large neighbourhood Benders' search, where the cut generated in the sub-SCIP solve are transferred to the main
6907 * SCIP instance.
6908 *
6909 * The BENDERSCUTEXEC callback must return the result of the cut generation. The permissable results are:
6910 * - if the Benders' cut was not run (SCIP_DIDNOTRUN).
6911 * - if the Benders' cut was run, but there was an error in generating the cut (SCIP_DIDNOTFIND).
6912 * - if the Benders' decomposition cut algorithm has not generated a constraint or cut (SCIP_FEASIBLE).
6913 * - an additional constraint for the Benders' decomposition cut was generated (SCIP_CONSADDED).
6914 * - a cutting plane representing the Benders' decomposition cut was generated (SCIP_SEPARATED).
6915 *
6916 * If the BENDERSCUTEXEC callback returns SCIP_DIDNOTFIND due to an error in the cut generation, if no other subproblems
6917 * generate a cut during the same iteration of the Benders' decomposition algorithm, then this could result in an
6918 * error. It is possible to avoid the error by merging the subproblem into the master problem (see \ref
6919 * BENDERSPOSTSOLVE).
6920 *
6921 * @section BENDERSCUT_ADDITIONALCALLBACKS Additional Callback Methods of a Separator
6922 *
6923 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
6924 * implemented for most applications, they can be used, for example, to initialize and free private data.
6925 * Additional callbacks can either be passed directly with SCIPincludeBenderscut() to SCIP or via specific
6926 * <b>setter functions</b> after a call of SCIPincludeBenderscutBasic(), see also @ref BENDERSCUT_INTERFACE.
6927 *
6928 * @subsection BENDERSCUTFREE
6929 *
6930 * If you are using Benders' decomposition cut data (see \ref BENDERSCUT_DATA and \ref BENDERSCUT_INTERFACE), you have
6931 * to implement this method in order to free the Benders' decomposition cut data.
6932 *
6933 * If you have allocated memory for fields in your Benders' decomposition cut data, remember to free this memory
6934 * before freeing the Benders' decomposition data itself.
6935 * If you are using the C++ wrapper class, this method is not available.
6936 * Instead, just use the destructor of your class to free the member variables of your class.
6937 *
6938 * @subsection BENDERSCUTCOPY
6939 *
6940 * The BENDERSCUTCOPY callback is executed when a SCIP instance is copied, e.g. to
6941 * solve a sub-SCIP. By
6942 * defining this callback as
6943 * <code>NULL</code> the user disables the execution of the specified
6944 * separator for all copied SCIP instances. This may deteriorate the performance
6945 * of primal heuristics using sub-SCIPs.
6946 *
6947 * If the Benders' decomposition cuts are included by calling SCIPincludeBendersDefaultCuts() in the include method of
6948 * the Benders' decomposition implementation, such as SCIPincludeBendersDefault(), then it is not necessary to implement
6949 * BENDERSCUTCOPY. The copy method could be implemented to copy Benders' decomposition cut data from the original SCIP
6950 * instance to the sub-SCIP.
6951 *
6952 *
6953 * @subsection BENDERSCUTINIT
6954 *
6955 * The BENDERSCUTINIT callback is executed after the problem is transformed The Benders' decomposition cut method may,
6956 * e.g., use this call to initialize its Benders' decomposition cut data. The difference between the original and the
6957 * transformed problem is explained in "What is this thing with the original and the transformed problem about?" on \ref
6958 * FAQ.
6959 *
6960 * @subsection BENDERSCUTEXIT
6961 *
6962 * The BENDERSCUTEXIT callback is executed before the transformed problem is freed. In this method, the Benders'
6963 * decomposition cut method should free all resources that have been allocated for the solving process in
6964 * BENDERSCUTINIT.
6965 *
6966 * @subsection BENDERSCUTINITSOL
6967 *
6968 * The BENDERSCUTINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
6969 * begin. The Benders' decomposition implementation may use this call to initialize its branch-and-bound specific data.
6970 *
6971 * @subsection BENDERSCUTEXITSOL
6972 *
6973 * The BENDERSCUTEXITSOL callback is executed before the branch-and-bound process is freed. The Benders' decomposition
6974 * implementation should use this call to clean up its branch-and-bound data.
6975 *
6976 */
6977/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6978
6979/**@page CONF How to use conflict analysis
6980 *
6981 * Conflict analysis is a way to automatically use the information obtained from infeasible nodes
6982 * in the branch-and-bound tree.
6983 *
6984 * Once a node is declared infeasible, SCIP automatically tries to infer a constraint that explains the reason for the
6985 * infeasibility, in order to avoid similar situations later in the search. This explanation essentially consists of a
6986 * constraint stating that at least one of its variables should have a bound different from the current infeasible node,
6987 * because the current setting led to infeasibility. Clearly, all variables that are fixed in the current infeasible
6988 * node would yield such a constraint (since this leads to infeasibility). The key point rather is to infer a "small"
6989 * constraint that does the same job. SCIP handles this by several heuristics. For this, SCIP sets up a
6990 * so-called (directed) conflict graph. The nodes in this graph correspond to bound changes of variables and an arc (@a
6991 * 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
6992 * will have several ingoing arcs which represent all bound changes that have been used to infer (propagate) the bound
6993 * change in question. The graph also contains source nodes for each bound that has been changed during branching and an
6994 * artificial target node representing the conflict, i.e., the infeasibility. Essentially, SCIP heuristically constructs
6995 * a cut in this graph that involves few "branching nodes". For details on the techniques that SCIP uses,
6996 * we refer to the paper @par
6997 * Tobias Achterberg, Conflict Analysis in Mixed Integer Programming@n
6998 * Discrete Optimization, 4, 4-20 (2007)
6999 *
7000 * For conflict analysis to work well, the author of a \ref CONS "Constraint Handler" or a
7001 * \ref PROP "Propagator" has to implement three kinds of functionality:
7002 *
7003 * -# If one detects infeasibility, one should initiate conflict analysis, see \ref INITCONFS "below".
7004 * -# During propagation, one should call the right functions to fix variables.
7005 * -# One should implement the <em>so-called reverse propagation</em>.
7006 *
7007 * If this functionality is not implemented, SCIP will still work correctly, but cannot use the information of the constraint
7008 * handler or the propagator for conflict analysis. In this case, each bound reduction performed by the constraint
7009 * handler/propagator will be treated as if it had been a branching decision.
7010 *
7011 * @section INITCONFS Initiating Conflict Analysis
7012 *
7013 * If one detects infeasibility within propagation, one should do the following:
7014 * -# Call SCIPinitConflictAnalysis().
7015 * -# Inform SCIP about the variable bounds that are the reason for the detection of infeasibility
7016 * via the functions SCIPaddConflictLb(), SCIPaddConflictUb(), SCIPaddConflictBd(), or
7017 * SCIPaddConflictBinvar(). If there is more than one valid explanation of infeasibility, either one can be used.
7018 * Typically, smaller explanations tend to be better.
7019 * -# Call SCIPanalyzeConflict() from a propagator or SCIPanalyzeConflictCons() from a constraint
7020 * handler.
7021 *
7022 * This functionality allows SCIP to set up the conflict graph and perform a conflict analysis.
7023 *
7024 * @section Propagation
7025 *
7026 * When propagating variable domains, SCIP needs to be informed that the deduced variable bounds should be
7027 * used in conflict analysis. This can be done by the functions SCIPinferVarLbCons(),
7028 * SCIPinferVarUbCons(), and SCIPinferBinvarCons() for constraint handlers and SCIPinferVarLbProp(),
7029 * SCIPinferVarUbProp(), and SCIPinferBinvarProp() for propagators. You can pass one integer of
7030 * information that should indicate the reason of the propagation and can be used in reverse
7031 * propagation, see the next section.
7032 *
7033 * @section RESPROP Reverse Propagation
7034 *
7035 * Reverse Propagation is used to build up the conflict graph. Essentially, it provides an algorithm to detect the arcs
7036 * leading to a node in the conflict graph, i.e., the bound changes responsible for the new bound change deduced during
7037 * propagation. Reverse Propagation needs to be implemented in the RESPROP callback functions of
7038 * \ref CONSRESPROP "constraint handlers" or \ref PROPRESPROP "propagators".
7039 * These callbacks receive the following information: the variable which is under investigation (@p
7040 * infervar), the corresponding bound change (@p bdchgidx, @p boundtype), and the integer (@p inferinfo) that has been
7041 * supplied during propagation.
7042 *
7043 * One can use SCIPvarGetUbAtIndex() or SCIPvarGetLbAtIndex() to detect the bounds before or after the propagation that
7044 * should be investigated. Then the bounds that were involved should be passed to SCIP via SCIPaddConflictLb() and
7045 * SCIPaddConflictUb(). If there is more than one valid explanation of infeasibility, either one can be used.
7046 * Typically, smaller explanations tend to be better.
7047 *
7048 * Details and (more) examples are given in Sections @ref CONSRESPROP and @ref PROPRESPROP.
7049 *
7050 *
7051 * @section Example
7052 *
7053 * Consider the constraint handler @p cons_linearordering.c in the
7054 * \ref LOP_MAIN "linear ordering example"
7055 * (see @p example/LOP directory). This constraint handler propagates the equations \f$x_{ij} + x_{ji} =
7056 * 1\f$ and triangle inequalities \f$x_{ij} + x_{jk} + x_{ki} \leq 2\f$.
7057 *
7058 * When propagating the equation and <code>vars[i][j]</code> is fixed to 1, the constraint handler uses
7059 * \code
7060 * SCIP_CALL( SCIPinferBinvarCons(scip, vars[j][i], FALSE, cons, i*n + j, &infeasible, &tightened) );
7061 * \endcode
7062 * Thus, variable <code>vars[j][i]</code> is fixed to 0 (@p FALSE), and it passes <code>i*n + j </code> as @p inferinfo.
7063 *
7064 * When it propagates the triangle inequality and both <code>vars[i][j]</code> and <code>vars[j][k]</code>
7065 * are fixed to 1, the constraint handler uses
7066 * \code
7067 * SCIP_CALL( SCIPinferBinvarCons(scip, vars[k][i], FALSE, cons, n*n + i*n*n + j*n + k, &infeasible, &tightened) );
7068 * \endcode
7069 * 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
7070 * passed as <code>inferinfo</code>.
7071 *
7072 * In reverse propagation, the two cases can be distinguished by @p inferinfo: if it is less than @p n*n,
7073 * we deal with an equation, otherwise with a triangle inequality. The constraint handler can then extract the
7074 * indices @p i, @p j (and @p k in the second case) from inferinfo.
7075 *
7076 * In the first case, it has to distinguish whether <code>vars[i][j]</code> is fixed to 0 or 1 &ndash;
7077 * by calling SCIPaddConflictLb()
7078 * or SCIPaddConflictUb(), respectively, with variable <code>vars[j][i]</code>. In the second case, it is clear that the only
7079 * 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>
7080 * are fixed to 1. It then calls
7081 * SCIPaddConflictLb() for both <code>vars[k][i]</code> and <code>vars[j][k]</code>.
7082 */
7083
7084/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7085
7086/**@page REOPT How to use reoptimization
7087 *
7088 * The reoptimization feature of SCIP can be used to solve a sequence of optimization problems \f$(P_{i})_{i \in I}\f$ with
7089 * \f[
7090 * (P_i) \quad \min \{ c_i^T x \;|\; A^ix \geq b^i,\; x_{j} \in \mathbb{Z}\;\forall j \in \mathcal{I} \}
7091 * \f]
7092 * 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
7093 * function changes. To use reoptimization the user has to change the parameter <code>reoptimization/enable</code> to
7094 * <code>TRUE</code> before the solving process of the first problem of the sequence starts, i.e., in stage
7095 * <code>SCIP_STAGE_INIT</code> or <code>SCIP_STAGE_PROBLEM</code>. This can be done via the interactive shell or by
7096 * calling SCIPenableReoptimization(). In both cases SCIP changes some parameters and fixes them:
7097 * -# disable conflict analysis based on dual information
7098 * -# set the limit <code>maxorigsol</code> of stored solutions to zero because this is handled by a special solution tree provided
7099 * by the reoptimization feature itself
7100 * -# disable restarts (<code>presolving/maxrestarts = 0</code>)
7101 * -# disable multi-aggegations (<code>presolving/donotmultaggr = TRUE</code>)
7102 * -# disable dual reductions within presolvers and propagators (<code>misc/allowdualreds = FALSE</code>)
7103 * -# disable propagation with current cutoff bound (<code>misc/allowobjprop = FALSE</code>)
7104 *
7105 * In contrast to the presolving and propagating methods that are using dual information, performing strong branching is
7106 * allowed. The bound tightenings resulting from strong branching are handeled in a special way. After changing the objective
7107 * function and solving the modified problem the feasible region that was pruned by strong branching will be reconstructed
7108 * within the tree.
7109 *
7110 * If the reoptimization feature is enabled SCIP tries to reuse the search tree, especially the search frontier at the end
7111 * of the solving process, to speed up the solving process of the following problems. Therefore, the current release
7112 * provides the branching rule <code>branch_nodereopt</code> to reconstruct the tree. SCIP triggers a restart of the
7113 * reoptimization, i.e., solving the problem from scratch, if
7114 *
7115 * -# the stored search tree is too large,
7116 * -# the objective functions changed too much, or
7117 * -# the last \f$n\f$ optimal solution are updated solution of previous runs.
7118 *
7119 * The thresholds to trigger a restart can be set by the user:
7120 *
7121 * -# <code>reoptimization/maxsavednodes</code>
7122 * -# <code>reoptimization/delay</code>
7123 * -# <code>reoptimization/forceheurrestart</code>
7124 *
7125 * Before SCIP discards all the stored information and solves the problem from scratch it tries to compress the search
7126 * tree. Therefore, the current release provides compression heuristics that try to find a good and much smaller
7127 * representation of the current search tree.
7128 *
7129 * After a problem in the sequence of optimization problems was solved, the objective function can be changed in two ways:
7130 * -# Using the provided reader <code>reader_diff</code> the objective function can be changed via using the interactive
7131 * shell
7132 * \code
7133 * SCIP> read new_obj.diff
7134 * \endcode
7135 * or by calling SCIPreadDiff().
7136 * -# The objective function can be changed within the code. Therefore, the transformed problem needs to be freed by
7137 * calling SCIPfreeReoptSolve(). Afterwards, the new objective function can be installed by calling
7138 * SCIPchgReoptObjective().
7139 *
7140 * After changing the objective function the modified problem can be solved as usal.
7141 *
7142 * \note Currently, the compression heuristics used between two successive reoptimization runs only support pure binary
7143 * and mixed binary programs.
7144 *
7145 * For more information on reoptimization we refer to@par
7146 * Jakob Witzig@n
7147 * Reoptimization Techniques in MIP Solvers@n
7148 * Master's Thesis, Technical University of Berlin, 2014.
7149 */
7150
7151/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7152
7153/**@page CONCSCIP How to use the concurrent solving mode
7154 *
7155 * @section Overview
7156 *
7157 * In \SCIP 4.0 a new feature has been added that allows to run multiple \SCIP instances with different settings
7158 * on one problem in parallel. To use this feature \SCIP has to be compiled with an additional make option to
7159 * enable the threading functionality (e.g. TPI=tny, see \ref MAKE).
7160 * Then, a concurrent solve can be started by using the <code>concurrentopt</code> command instead of the <code>optimize</code> command
7161 * in the \SCIP shell, or by calling the interface function SCIPsolveParallel().
7162 * To configure the behavior of the concurrent solving mode there are new parameters in the category <code>concurrent/</code>
7163 * and <code>parallel/</code> which will be explained here shortly.
7164 *
7165 * @section CONTROLNTHREADS Controlling the number of threads
7166 *
7167 * The parameters <code>parallel/maxnthreads</code> and <code>parallel/minnthreads</code> can be used to configure the number of threads
7168 * that sould be used for solving. \SCIP will try to use the configured maximum number of threads. If the
7169 * problem that is currently read is too large \SCIP will automatically use fewer threads, but never
7170 * go below the configured minimum number of threads.
7171 *
7172 * @section USEEMPHSETTINGS Using emphasis settings
7173 *
7174 * The parameters <code>concurrent/scip.../prefprio</code> configure which concurrent solvers should be used.
7175 * The concurrent solver <code>scip</code> will use the same settings as the \SCIP instance configured by the user.
7176 * The other concurrent solvers, e.g. <code>scip-feas</code>, will load the corresponding emphasis setting.
7177 * The behavior of the prefprio parameter is as follows: If it is set to 1.0 for <code>scip-feas</code> and
7178 * <code>scip-opti</code>, and to 0.0 for every other concurrent solver, then the threads will be evenly
7179 * 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
7180 * 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
7181 * and the latter will use 3 threads of the 4 available threads.
7182 *
7183 * @section CUSTOMCONCSOLVERS Running custom solvers
7184 *
7185 * To use custom settings for the concurrent solvers there is the parameter <code>concurrent/paramsetprefix</code>. If custom parameters
7186 * 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).
7187 * The parameter settings must be named after the concurrent solvers, e.g. if only the concurrent solver <code>scip</code> is used
7188 * 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
7189 * starts at one for each of them, e.g. <code>scip-1</code> and <code>scip-feas-1</code>.
7190 */
7191
7192/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7193
7194/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7195
7196/**@page DECOMP How to provide a problem decomposition
7197 *
7198 * Most mixed-integer programs have sparse constraint matrices in the sense that most columns and rows have only very few nonzero entries,
7199 * maybe except for a few outlier columns/rows with many nonzeros.
7200 * 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
7201 * columns, but are otherwise independent.
7202 * The special case of completely independent subproblems (with no linking rows and columns), for example, can be solved by solving
7203 * the much smaller subproblems and concatenating their optimal solutions.
7204 * This case has already been integrated into SCIP as a successful presolving technique (see @ref cons_components.c).
7205 * Another use of decomposition within SCIP is the @ref BENDDECF "Benders Decomposition framework".
7206 *
7207 * Since SCIP 7.0, it is easier to pass user decompositions to SCIP that can be used within Benders decomposition or by user algorithms.
7208 * This page introduces the struct SCIP_DECOMP and gives examples how to create and use it.
7209 *
7210 * @section DECOMP_OVERVIEW Overview
7211 *
7212 * In the following, we present decompositions of mixed-integer programs. However, the generalization to Constraint Integer Programs is straightforward.
7213 *
7214 * 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,
7215 *
7216 * \f[
7217 * 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}})
7218 * \f]
7219 * 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$.
7220 * 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.
7221 * In other words, the inequality system \f$A x \geq b\f$ can be rewritten
7222 * with respect to a decomposition \f$\mathcal{D}\f$ by a suitable permutation of the rows
7223 * and columns of \f$A\f$ as equivalent system
7224 * \f[
7225 * \left(
7226 * \begin{matrix}
7227 * A_{[D^{\text{row}}_{1},D^{\text{col}}_{1}]} &
7228 * 0 &
7229 * \cdots &
7230 * 0 &
7231 * A_{[D^{\text{row}}_{1},L^{\text{col}}]}\\
7232 * 0 &
7233 * A_{[D^{\text{row}}_{2},D^{\text{col}}_{2}]} &
7234 * 0 &
7235 * 0 &
7236 * A_{[D^{\text{row}}_{2},L^{\text{col}}]}\\
7237 * \vdots &
7238 * 0 &
7239 * \ddots &
7240 * 0 &
7241 * \vdots\\
7242 * 0 &
7243 * \cdots &
7244 * 0 &
7245 * A_{[D^{\text{row}}_{k},D^{\text{col}}_{k}]} &
7246 * A_{[D^{\text{row}}_{k},L^{\text{col}}]}\\
7247 * A_{[L^{\text{row}},D^{\text{col}}_{1}]} &
7248 * A_{[L^{\text{row}},D^{\text{col}}_{2}]} &
7249 * \cdots &
7250 * A_{[L^{\text{row}},D^{\text{col}}_{k}]} &
7251 * A_{[L^{\text{row}},L^{\text{col}}]}
7252 * \end{matrix}
7253 * \right)
7254 * \left(
7255 * \begin{matrix}
7256 * x_{[D^{\text{col}}_{1}]}\\
7257 * x_{[D^{\text{col}}_{2}]}\\
7258 * \vdots\\
7259 * x_{[D^{\text{col}}_{k}]}\\
7260 * x_{[L^{\text{col}}]}
7261 * \end{matrix}
7262 * \right)
7263 * \geq
7264 * \left(
7265 * \begin{matrix}
7266 * b_{[D^{\text{row}}_{1}]}\\
7267 * b_{[D^{\text{row}}_{2}]}\\
7268 * \vdots\\
7269 * b_{[D^{\text{row}}_{k}]}\\
7270 * b_{[L^{\text{row}}]}
7271 * \end{matrix}
7272 * \right)
7273 * % A= \left(\begin{matrix}4&8&\frac{1}{2}\\\frac{3}{2}&4&1\\1&3&7\end{matrix}\right)
7274 * \f]
7275 * where we use the short hand syntax \f$A_{[I,J]}\f$ to denote
7276 * the \f$|I|\f$-by-\f$|J|\f$ submatrix that arises from the deletion of all entries
7277 * from \f$A\f$ except for rows \f$I\f$ and columns \f$J\f$,
7278 * for nonempty row
7279 * and column subsets \f$I\subseteq\{1,\dots,m\}\f$ and \f$J\subseteq\{1,\dots,n\}\f$.
7280 *
7281 *
7282 * @section DECOMP_USING Using a decomposition
7283 *
7284 * After passing one or more decompositions, see below, one can access all available decompositions with SCIPgetDecomps().
7285 * The labels can be obtained by calling SCIPdecompGetVarsLabels() and SCIPdecompGetConsLabels().
7286 * If some variables/constraints are not labeled, these methods will mark them as linking variables/constraints.
7287 * There are several methods to get more information about one decomposition, see @ref DecompMethods.
7288 *
7289 * A decomposition can be used to split the problem into several subproblems which, in general, are easier to solve.
7290 * For \f$q \in \{1,\dots,k\}\f$ the system
7291 * \f[
7292 * A_{[D^{\text{row}}_{q},D^{\text{col}}_{q}]}\; x_{[D^{\text{col}}_{q}]} \geq b_{[D^{\text{row}}_{q}]}
7293 * \f]
7294 * is part of subproblem \f$q\f$, the handling of the linking variables/constraints depends on the chosen application context.
7295 * For example, in the heuristic @ref heur_padm.c several smaller subproblems are solved multiple times to get a feasible solution.
7296 * Also the @ref BENDDECF "Benders' decomposition framework" was extended with release 7.0 to use user decompositions.
7297 *
7298 * @section DECOMP_CREATION Creation via SCIP-API
7299 *
7300 * There are two different ways to provide a decomposition in SCIP.
7301 * It can be created with the SCIP-API or it can be read from a file.
7302 *
7303 * To create it with the API, the user must first create a decomposition with SCIPcreateDecomp() specifying
7304 * whether the decomposition belongs to the original or transformed problem and the number of blocks.
7305 * Then the variables and constraints can be assigned to one block or to the linking rows/columns by calling
7306 * SCIPdecompSetVarsLabels() and SCIPdecompSetConsLabels(), respectively.
7307 * To complete the decomposition or to ensure that it is internally consistent, SCIPcomputeDecompVarsLabels() or
7308 * SCIPcomputeDecompConsLabels() can be called.
7309 * Note that SCIPcomputeDecompVarsLabels() will ignore the existing variable labels and computes again the labels based on the constraint labels only;
7310 * SCIPcomputeDecompConsLabels() works in the same way and ignores the existing constraint labels.
7311 *
7312 * After the decomposition has been successfully created, it can be saved for later use in the DecompStore using SCIPaddDecomp().
7313 * Access to all decompositions in the DecompStore is possible with SCIPgetDecomps().
7314 *
7315 * @section DECOMP_READDEC Reading a decomposition from a file
7316 *
7317 * Alternatively, after a problem has been read, a related decomposition can be read from a dec-file.
7318 * Please refer to the @ref reader_dec.h "DEC file reader" for further information about the required file format.
7319 * 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.
7320 *
7321 * @section DECOMP_BENDERS Use for Benders
7322 *
7323 * 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.
7324 * With this setting, the variable's labeling takes place giving precedence to its presence in linking constraints over its presence in named blocks.
7325 *
7326 * @section DECOMP_TRANS Decomposition after problem transformation
7327 *
7328 * As the problem's constraints are constantly changing, or possibly deleted, during presolving, the constraints' labeling must be triggered again.
7329 * Therefore, SCIP automatically transforms all user decompositions at the beginning of the root node based on the variables' labels.
7330 *
7331 * @section DECOMP_STATS Decomposition statistics
7332 *
7333 * Further useful measures and statistics about the decomposition are computed within SCIPcomputeDecompStats().
7334 * When the labeling process is concluded, the following measures are computed and printed:
7335 * - the number of blocks;
7336 * - the number of linking variables and linking constraints;
7337 * - the size of the largest as well as the smallest block;
7338 * - the area score:
7339 * This score is also used by GCG to rank decompositions during the automatic detection procedure.
7340 * For a decomposition
7341 * \f$\mathcal{D}=(D^{\text{row}},D^{\text{col}})\f$,
7342 * the area score is defined as
7343 * \f[
7344 * \text{areascore}(\mathcal{D}) = 1 - \frac{ \sum_{q=1}^k \lvert D^{\text{row}}_{q} \rvert
7345 * \lvert D^{\text{col}}_{q} \rvert + n\lvert L^{\text{row}} \rvert + m\lvert L^{\text{col}} \rvert -
7346 * \lvert L^{\text{row}} \rvert \lvert L^{\text{col}} \rvert }{mn}
7347 * \enspace.
7348 * \f]
7349 * In the case of a mixed-integer program, the area score intuitively measures the coverage of the rearranged matrix by 0's.
7350 * Decompositions with few linking variables and/or constraints and many small blocks \f$A_{[D^{\text{row}}_{q},D^{\text{col}}_{q}]}\f$
7351 * will have an area score close to \f$1\f$, whereas coarse decompositions of a matrix have smaller area scores.
7352 * The trivial decomposition with a single block has the worst possible area score of 0.
7353 * - the modularity:
7354 * This measure is used to assess the quality of the community structure within a decomposition.
7355 * The modularity of the decomposition is computed as follows:
7356 * \f[
7357 * \begin{aligned}
7358 * \sum_{q=1}^{k} \dfrac{e_{q}}{m} \left(1-\dfrac{e_{q}}{m}\right),
7359 * \end{aligned}
7360 * \f]
7361 * 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.
7362 * The presence of an inner edge is identified through the presence of a variable in a constraint,
7363 * both—the variable and the constraint—belonging to the same block.
7364 * - 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.
7365 * Note that the linking constraints are intentionally skipped in this computation.
7366 * \f$ G = (V,E) \f$ denotes a block graph, with vertex set \f$V\f$ and edge set \f$E\f$.
7367 * Each vertex in the graph represents a block in the decomposition; \f$V = \{v_{1},\dots,v_{k}\}\f$.
7368 * 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$
7369 * 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$.
7370 * From the constructed graph, the number of edges, articulation points and connected components are computed, together with the maximum and minimum degree.
7371 * Note that building the block graph can become computationally expensive with large and dense decompositions.
7372 * Thus, it is possible through a user parameter <code>decomposition/maxgraphedge</code> to define a maximum edge limit.
7373 * 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.
7374 *
7375 */
7376
7377/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7378
7379
7380/**@page BENDDECF How to use the Benders' decomposition framework
7381 *
7382 * Benders' decomposition is a very popular mathematical programming technique that is applied to solve structured
7383 * problems. Problems that display a block diagonal structure are particularly amenable to the application of Benders'
7384 * decomposition. In a purely mixed-integer linear setting, such problems are given by
7385 *
7386 * \f[
7387 * \begin{array}[t]{rllclcl}
7388 * \min & \displaystyle & c^{T}x & + & d^{T}y \\
7389 * & \\
7390 * \text{subject to} & \displaystyle & Ax & & & = & b \\
7391 * & \\
7392 * & \displaystyle & Tx & + & Hy & = & h \\
7393 * & \\
7394 * & & x & & & \in & \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
7395 * & & & & y & \in & \mathbb{R}^{m} \\
7396 * \end{array}
7397 * \f]
7398 *
7399 * The variables \f$x\f$ and \f$y\f$ are described as the first and second stage variables respectively. In the
7400 * classical use of Benders' decomposition, it is a requirement that the all second stage variables are continuous.
7401 * Extensions to the classical Benders' decomposition approach have permitted the use of more general second stage
7402 * problems.
7403 *
7404 * The application of Benders' decomposition to the above problem results in a subproblem, given by
7405 *
7406 * \f[
7407 * \begin{array}[t]{rll}
7408 * \min & \displaystyle & d^{T}y \\
7409 * & \\
7410 * \text{subject to} & \displaystyle & Hy = h - T\bar{x} \\
7411 * & \\
7412 * & & y \in \mathbb{R}^{m} \\
7413 * \end{array}
7414 * \f]
7415 *
7416 * where \f$\bar{x}\f$ is a solution vector of the first stage variables. As such, the subproblem is a problem only in
7417 * \f$y\f$. The dual solution to the subproblem, either an extreme point or extreme ray, is used to generate cuts that
7418 * are added to the master problem. Let \f$\lambda\f$ be the vector of dual variables associated with the set of
7419 * constraints from the subproblem. If, for a given \f$\bar{x}\f$, the subproblem is infeasible, then \f$\lambda\f$
7420 * corresponds to a dual ray and is used to produce the cut
7421 *
7422 * \f[
7423 * 0 \geq \lambda(h - Tx)
7424 * \f]
7425 *
7426 * which eliminates \f$\bar{x}\f$ from the master problem. If, for a given \f$\bar{x}\f$, the subproblem is feasible,
7427 * then \f$\lambda\f$ corresponds to a dual extreme point and is used to produce the cut
7428 *
7429 * \f[
7430 * \varphi \geq \lambda(h - Tx)
7431 * \f]
7432 *
7433 * where \f$\varphi\f$ is an auxiliary variable added to the master problem as an underestimator of the optimal
7434 * subproblem objective function value.
7435 *
7436 * Given \f$\Omega^{p}\f$ and \f$\Omega^{r}\f$ as the sets of dual extreme points and rays of the subproblem,
7437 * respectively, the Benders' decomposition master problem is given by
7438 *
7439 * \f[
7440 * \begin{array}[t]{rll}
7441 * \min & \displaystyle & c^{T}x + \varphi \\
7442 * & \\
7443 * \text{subject to} & \displaystyle & Ax = b \\
7444 * & \\
7445 * & \displaystyle & \varphi \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r}\\
7446 * & \\
7447 * & \displaystyle & 0 \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r} \\
7448 * & \\
7449 * & & x \in \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
7450 * & & \varphi \in \mathbb{R} \\
7451 * \end{array}
7452 * \f]
7453 *
7454 * @section BENDERFRAMEWORK Overview
7455 *
7456 * In \SCIP 6.0 a Benders' decomposition framework has been implemented.
7457 *
7458 * The current framework can be used to handle a Benders Decomposition of CIPs of the form
7459 *
7460 * \f[
7461 * \begin{array}[t]{rllclcl}
7462 * \min & \displaystyle & c^{T}x & + & d^{T}y \\
7463 * \text{subject to} & \displaystyle & g(x & , & y) & \in & [\ell,u] \\
7464 * & & x & & & \in & X \\
7465 * & & & & y & \in & Y \\
7466 * \end{array}
7467 * \f]
7468 * when either
7469 * - 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
7470 * - the first stage variables are of binary type: \f$ X \subseteq \{0,1\}^n \f$.
7471 *
7472 * This framework can be used in four different
7473 * ways: inputting an instance in the SMPS file format, using the default Benders' decomposition implementation
7474 * (see src/scip/benders_default.c), implementing a custom Benders' decomposition plugin (see \ref BENDER), or by using
7475 * the Benders' decomposition mode of GCG.
7476 * An overview of how to use each of these methods will be provided in this section.
7477 *
7478 * @section BENDERSSMPS Inputting an instance in the SMPS file format.
7479 *
7480 * As part of the Benders' decomposition framework development, a reader for instances in the SMPS file format has been
7481 * implemented (see src/scip/reader_smps.c). The details regarding the SMPS file format can be found at:
7482 *
7483 * Birge, J. R.; Dempster, M. A.; Gassmann, H. I.; Gunn, E.; King, A. J. & Wallace, S. W.
7484 * A standard input format for multiperiod stochastic linear programs
7485 * IIASA, Laxenburg, Austria, WP-87-118, 1987
7486 *
7487 * In brief, the SMPS file format involves three different files:
7488 * - A core file (.cor): a problem instance in MPS format that is the core problem of a stochastic program.
7489 * - A time file (.tim): partitions the variables and constraints into the different stages of the stochastic program
7490 * - A stochastic file (.sto): describes the scenarios for each stage.
7491 *
7492 * The STO reader (see src/scip/reader_sto.c) constructs the stochastic program using the information from the core and
7493 * time files. By default, the STO reader will construct the deterministic equivalent of the stochastic program. A
7494 * parameter is provided "reading/sto/usebenders" that will inform the STO reader to apply Benders' decomposition to the
7495 * input stochastic program.
7496 *
7497 * @section BENDERSDEFAULT Using the default Benders' decomposition plugin.
7498 *
7499 * A default implementation of a Benders' decomposition plugin has been included in \SCIP 6.0 (see
7500 * src/scip/benders_default.c). In order to use the default plugin, the user must create SCIP instances of the master
7501 * problem and subproblems. The subproblems must also contain a copy of the master problem variables, since these are
7502 * fixed to the master problem solution values during the subproblem solving loop. These SCIP instances for the master
7503 * and subproblems are passed to the default plugin by calling SCIPcreateBendersDefault().
7504 *
7505 * The mapping between the master and subproblem variables is performed automatically. The default solving and cut
7506 * generation methods are applied to solve the input problem. It is important to note that the mapping between the
7507 * master and subproblem variables relies on the variable names. The variables of the subproblem corresponding to
7508 * master problem variables must have the same name in both problems.
7509 *
7510 * The CAP (stochastic capacitated facility location problem) example demonstrates the use of the default Benders'
7511 * decomposition implementation within a project.
7512 *
7513 * @section BENDERSCUSTOM Implementing a custom Benders' decomposition implementation.
7514 *
7515 * A custom Benders' decomposition requires the implementation of a Benders' decomposition plugin. The key aspects for
7516 * implementing a custom Benders' decomposition plugin are explained in \ref BENDER.
7517 *
7518 * @section BENDERSGCG Using the Benders' decomposition mode of GCG
7519 *
7520 * In GCG 3.0, a Benders' decomposition mode has been implemented. This mode takes the decomposition found by the
7521 * detection schemes of GCG and applies Benders' decomposition. Using GCG it is possible to apply Benders' decomposition
7522 * to general problem without having to manually construct the decompositions.
7523 *
7524 */
7525
7526/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7527
7528/**@page PROBINGDIVING How to use probing and diving mode
7529 *
7530 * SCIP contains two methods to perform a temporary dive in the branch-and-bound tree: the diving mode and the probing mode.
7531 * Both methods enable the modification of variable bounds, addition of new constraints, or adjustments to the objective function.
7532 * 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.
7533 * 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.
7534 *
7535 * 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.
7536 * 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].
7537 * To reset all changes, the respective mode needs to be ended by calling SCIPendDive() and SCIPendProbing(), respectively.
7538 *
7539 * 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.
7540 * 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.
7541 * Similarly, the function SCIPpropagateProbing() might find globally valid bound changes, which are added to the main SCIP and considered in the subsequent solving process.
7542 * Another way to leverage insights found during probing or diving is to update pseudo costs during both modes, helping make better branching decisions.
7543 * This is controlled by setting the parameter "divingpscosts" to TRUE, which is done in the default settings of SCIP.
7544 * 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.
7545 * In some cases, such as when dealing with a numerically difficult instance, this might lead to a different LP state.
7546 * Finally, during probing, global variable statistics can be collected by calling SCIPenableVarHistory() after starting probing.
7547 * 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.
7548 *
7549 */
7550/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7551
7552/**@page OBJ Creating, capturing, releasing, and adding data objects
7553 *
7554 * Data objects (variables, constraints, rows, ... ) are subject to reference counting
7555 * to avoid expensive copying operations. This concept is similar to smart pointers.
7556 * Creating such an object (e.g., by calling SCIPcreateVar()) will set the
7557 * reference counter to one. Capturing an object (e.g., by calling SCIPcaptureVar()) increases the reference counter,
7558 * releasing it (e.g., by calling SCIPreleaseVar()) decreases the counter. If the reference counter gets zero, the
7559 * object will be destroyed automatically.
7560 *
7561 * Remember that a created data object is automatically captured. If the user
7562 * doesn't need the object anymore, (s)he has to call the object's release method.
7563 *
7564 * When a data object is added to SCIP (e.g., by calling SCIPaddVar()) , it is captured again, such that a
7565 * release call does not destroy the object. If SCIP doesn't need the object
7566 * anymore, it is automatically released.
7567 *
7568 * E.g., if the user calls
7569 * \code
7570 * SCIPcreateVar(); // reference counter 1
7571 * SCIPaddVar(); // reference counter 2
7572 * SCIPreleaseVar(); // reference counter 1
7573 * \endcode
7574 * the reference counter will be 1 afterwards, and the variable will be destroyed, if SCIP frees the problem.
7575 * If the user wants to use this variable, e.g. for extracting statistics after SCIP was finished, the user must not call
7576 * SCIPreleaseVar() right after adding the variable, but before terminating the program.
7577 */
7578
7579/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7580
7581/**@page PARAM How to add additional user parameters
7582 *
7583 * Users may add their own parameters to SCIP by calling SCIPaddXyzParam(). Using
7584 * this method, there are two possibilities for where to store the actual parameter value:
7585 * - If the given valueptr is NULL, SCIP stores the parameter value internally, and
7586 * the user can only access the value with the SCIPgetXyzParam() and
7587 * SCIPsetXyzParam() calls.
7588 * - If the given valueptr is not NULL, SCIP stores the parameter value at the given
7589 * address, and the user can directly manipulate the value at this address.
7590 * (S)he has to be careful with memory management in string parameters: when the
7591 * SCIPaddStringParam() method is called, the given address must hold a char*
7592 * pointer with value NULL. The default value is then copied into this pointer,
7593 * allocating memory with BMSallocMemoryArray(). If the parameter is changed, the
7594 * old string is freed with BMSfreeMemoryArray() and the new one is copied to a new
7595 * memory area allocated with BMSallocMemoryArray(). When the parameter is freed,
7596 * the memory is freed with BMSfreeMemoryArray().
7597 * The user should not interfere with this internal memory management. Accessing
7598 * the string parameter through the given valueptr is okay as long as it does not
7599 * involve reallocating memory for the string.
7600 *
7601 * In some cases, it is necessary to keep track of changes in a parameter.
7602 * If this is the case, the user can define a method by the PARAMCHGD callback and use this method as
7603 * the @c paramchgd parameter of the @c SCIPaddXyzParam() method, also giving a pointer to the data, which is
7604 * needed in this method, as @c paramdata. If this method is not NULL, it is called every time
7605 * the value of the parameter is changed.
7606 */
7607
7608/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7609
7610/**@page MEMORY Using the memory functions of SCIP
7611 *
7612 * SCIP provides three ways for allocating memory:
7613 * -# <b>block memory:</b> efficient handling of memory blocks of similar small sizes
7614 * -# <b>buffer memory:</b> efficient handling of memory that needs to locally be allocated and freed
7615 * -# <b>standard memory:</b> access to standard malloc/free
7616 *
7617 * <em>Whenever possible, the first two should be used, because of reasons detailed below.</em>
7618 *
7619 * In the following, we provide a brief description of these methods. We refer the reader to the dissertation of Tobias
7620 * Achterberg for more details. We also present best practice models.
7621 *
7622 * @section MEMBACK Background
7623 *
7624 * The main goals for providing such particular methods are:
7625 * - <em>Accounting:</em> Using its own functions, SCIP knows the total size of memory allocated internally and can change its
7626 * behavior: for instance, it can change to "memory saving mode" (using depth first search (DFS) and possibly do a garbage
7627 * collection). It also allows for keeping a memory limit.
7628 * - <em>Speed:</em> SCIP often needs to allocate a very large number of small blocks of similar sizes (often powers of
7629 * two). Depending on the operating system and compiler, the methods implemented in SCIP can be faster, since blocks
7630 * of the same size are grouped together. Especially at the end of the 1990ies the standard malloc/free methods were
7631 * quite ineffective. The experiments of Tobias Achterberg in 2007 show a speed improvement of 11 % when using block
7632 * memory.
7633 * - <em>Efficiency:</em> Since blocks are groups in sizes, the blocks do not need to store their sizes within each
7634 * block. In comparison, standard malloc/free stores the size using one word for each memory chunk. The price to pay
7635 * is that one needs to pass the size to the methods that free a block. In any case, the methods in SCIP can save
7636 * memory. Moreover, buffer memory is stored in similar places and not spread out, which also might help cache.
7637 * - <em>Debugging:</em> All of the possibilities provide methods to detect memory leaks. Together with tools like
7638 * valgrind, this can be quite effective in avoiding such problems.
7639 *
7640 * @n
7641 * @section BLKMEM Block memory
7642 *
7643 * SCIP offers its own block memory handling, which allows efficient handling of smaller blocks of memory in cases in
7644 * which many blocks of the same (small) size appear. This is adequate for branch-and-cut codes in which small blocks
7645 * of the same size are allocated and freed very often (for data structures used to store rows or branch-and-bound
7646 * nodes). Actually, most blocks allocated within SCIP have small sizes like 8, 16, 30, 32, 64. The idea is simple:
7647 * There is a separate list of memory blocks for each interesting small size. When allocating memory, the list is
7648 * checked for a free spot in the list; if no such spot exists, the list is enlarged. Freeing just sets the block to be
7649 * available. Very large blocks are handled separately. See the dissertation of Tobias Achterberg for more details.
7650 *
7651 * One important comment is that freeing block memory requires the size of the block in order to find the right list.
7652 *
7653 * The most important functions are
7654 * - SCIPallocBlockMemory(), SCIPallocBlockMemoryArray() to allocate memory
7655 * - SCIPfreeBlockMemory(), SCIPfreeBlockMemoryArray() to free memory
7656 *
7657 * An example code is:
7658 * @refsnippet{tests/src/misc/snippets.c,SnippetArrayAllocAndFree}
7659 * @n
7660 *
7661 * @section BUFMEM Buffer memory
7662 *
7663 * @subsection BUFMEMSTD Standard Buffer Memory
7664 *
7665 * In addition to block memory, SCIP offers buffer memory. This should be used if memory is locally used within a
7666 * function and freed within the same function. For this purpose, SCIP has a list of memory buffers that are reused for
7667 * this purpose. In this way, a very efficient allocation/freeing is possible.
7668 *
7669 * Note that the buffers are organized in a stack, i.e., freeing buffers in reverse order of allocation is faster.
7670 *
7671 * The most important functions are
7672 * - SCIPallocBuffer(), SCIPallocBufferArray() to allocate memory,
7673 * - SCIPfreeBuffer(), SCIPfreeBufferArray() to free memory.
7674 *
7675 * @subsection BUFMEMCLEAN Clean Buffer Memory
7676 *
7677 * SCIP 3.2 introduced a new type of buffer memory, the <em>clean buffer</em>. It provides memory which is initialized to zero
7678 * and requires the user to reset the memory to zero before freeing it. This can be used at performance-critical
7679 * places where only few nonzeros are added to a dense array and removing these nonzeros individually is much faster
7680 * than clearing the whole array. Similar to the normal buffer array, the clean buffer should be used for temporary memory
7681 * allocated and freed within the same function.
7682 *
7683 * The most important functions are
7684 * - SCIPallocCleanBufferArray() to allocate memory,
7685 * - SCIPfreeCleanBufferArray() to free memory.
7686 *
7687 * @n
7688 * @section STDMEM Standard memory
7689 *
7690 * SCIP provides an access to the standard C functions @c malloc and @c free with the additional feature of tracking
7691 * memory in debug mode. In this way, memory leaks can be easily detected. This feature is automatically activated in
7692 * debug mode.
7693 *
7694 * The most important functions are
7695 * - SCIPallocMemory(), SCIPallocMemoryArray() to allocate memory,
7696 * - SCIPfreeMemory(), SCIPfreeMemoryArray() to free memory.
7697 *
7698 * @n
7699 * @section MEMBESTPRACTICE Best Practice of Using Memory Functions
7700 *
7701 * Since allocating and freeing memory is very crucial for the speed and memory consumption of a program, it is
7702 * important to keep the following notes and recommendations in mind.
7703 *
7704 * @subsection GEN General Notes
7705 *
7706 * The following holds for all three types of memory functions:
7707 * - In debug mode, the arguments are checked for overly large allocations (usually arising from a bug). Note that all
7708 * arguments are converted to unsigned values of type @c size_t, such that negative sizes are converted into very
7709 * large values.
7710 * - The functions always allocate at least one byte and return non-NULL pointers if memory is available. In particular,
7711 * freeing is always possible.
7712 * - The freeing methods set the pointer to the memory to NULL.
7713 * - Debugging can be supported by using the compiler flags @p NOBLKMEM=true, @p NOBUFMEM=true, @p NOBLKBUFMEM=true
7714 * that turn off the usage of block memory, buffer memory, as well as block and buffer memory, respectively. Since,
7715 * the internal block and buffer memory is freed at the end (leaving no memory leaks), turning them off allows tools
7716 * like valgrind to find memory leaks.
7717 * - Moreover, additional checks can be turned on by defining @p CHECKMEM in memory.c.
7718 *
7719 * @n
7720 * @subsection DOS Things to do ...
7721 *
7722 * - Use buffer memory if your memory chunk can be allocated and freed within the same function.
7723 * - Use buffer and block memory wherever possible, because of the reasons explained above.
7724 * - Free memory in the reverse order in which it was allocated! For block and buffer memory this @b significantly
7725 * speeds up the code.
7726 * - Use as few memory allocations/freeing operations as possible, since these functions take a significant amount of time.
7727 *
7728 * @n
7729 * @subsection DONTS Things to avoid ...
7730 *
7731 * - Avoid the usage of standard memory, since SCIP is unaware of the size used in such blocks.
7732 * - Avoid reallocation with only slightly increased size, rather use a geometrically growing
7733 * size allocation. SCIPcalcMemGrowSize() is one way to calculate new sizes.
7734 * - Be careful with buffer memory reallocation: For single buffers, the memory is reallocated (using malloc); since
7735 * the actual space might be larger than what was needed at allocation time, reallocation sometimes comes without
7736 * extra cost. Note that reallocating block memory in most cases implies moving memory arround.
7737 */
7738
7739/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7740
7741/**@page DEBUG Debugging
7742 *
7743 * If you need to debug your own code that uses SCIP, here are some tips and tricks:
7744 *
7745 * - Use <b>asserts</b> in your code to show preconditions for the parameters, invariants and postconditions.
7746 * Assertions are boolean expressions which inevitably have to evaluate to <code>TRUE</code>. Consider the
7747 * following example:
7748 *
7749 * @refsnippet{src/scip/cons_linear.c,SnippetDebugAssertions}
7750 *
7751 * As you can see, both pointers and integers are checked for valid values at the beginning of the
7752 * function <code>consCatchEvent()</code>. This is particularly important for, e.g., array indices like
7753 * the variable <code>pos</code> in this example, where using the <code>consdata->vars[pos]</code>
7754 * pointer could result in unexspected behaviour
7755 * if the asserted precondition on <code>pos</code> were not matched and <code>pos</code> were an arbitrary index
7756 * outside the array range.
7757 *
7758 * - In order to activate assertions, use the <b>Debug mode</b> by compiling SCIP via
7759 * \code
7760 * cmake -DCMAKE_BUILD_TYPE=Debug
7761 * \endcode
7762 * or the Makefile equivalent
7763 * \code
7764 * make OPT=dbg
7765 * \endcode and run the code. See \ref CMAKE and \ref MAKE for further information about compiler options for SCIP.
7766 * As a rule of thumb, Spending only little extra time on
7767 * asserting preconditions saves most of the time spent on debugging!
7768 *
7769 * - Turn on <b>additional debug output</b> by adding the line
7770 * \code
7771 * #define SCIP_DEBUG
7772 * \endcode
7773 * at the top of SCIP files you want to analyze. This will output messages included in the code using
7774 * <code>SCIPdebugMsg(scip, ...)</code> (or <code>SCIPdebugMessage()</code>), see \ref EXAMPLE_1.
7775 * We recommend to also use <code>SCIPdebugMsg(scip, ...)</code> in your own code for being able to activate
7776 * debug output in the same way.
7777 * - If available on your system, we recommend to use a debugger like <code>gdb</code>
7778 * to trace all function calls on the stack,
7779 * display values of certain expressions, manually break the running code, and so forth.
7780 * - If available on your system, you can use software like <a href="http://valgrind.org">valgrind</a> to check for uninitialized
7781 * values or segmentation faults.
7782 * - For checking the usage of SCIP memory, you can use
7783 * <code>SCIPprintMemoryDiagnostic()</code>. This outputs memory that is currently in use,
7784 * which can be useful after a <code>SCIPfree()</code> call.
7785 * - 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>
7786 * (or <code>make NOBLKBUFMEM=true</code> if you are using the Makefile system.
7787 * Also for the Makefile system, do not forget to clean your code before with <code>make OPT=... LPS=... clean</code>)
7788 * Only with that change, valgrind (or similar) reliably helps
7789 * to detect leaked memory.
7790 * - If your code cuts off a feasible solution, but you do not know which component is responsible,
7791 * you can use the debugging mechanism (see \ref EXAMPLE_2). Therefore, a given solution is read and it
7792 * is checked for every reduction, whether the solution will be pruned globally.
7793 *
7794 * @section EXAMPLE_1 How to activate debug messages
7795 * For example, if we include a <code>\#define SCIP_DEBUG</code> at the top of \ref heur_oneopt.c, recompile SCIP
7796 * in Debug mode, and run the SCIP interactive shell to solve p0033.mps from the
7797 * <a href="http://miplib2010.zib.de/miplib3/miplib.html">MIPLIB 3.0</a> , we get some output like:
7798 *
7799 * \include debugexamples/example1.txt
7800 *
7801 * @section EXAMPLE_2 How to add a debug solution
7802 *
7803 * Continuing the example above, we finish the solving process.
7804 * The optimal solution can now be written to a file:
7805 * \include debugexamples/example2_1.txt
7806 *
7807 * If we afterwards recompile SCIP with the additional compiler flag <code>cmake -DDEBUGSOL=on</code> (<code>make DEBUGSOL=true</code> in the Makefile system),
7808 * set the parameter <code>misc/debugsol = check/p0033.sol</code>, and run SCIP again it will output:
7809 * \include debugexamples/example2_2.txt
7810 * Further debug output would only appear, if the solution was cut off in the solving process.
7811 */
7812
7813/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7814
7815/**@page TEST How to run automated tests with SCIP
7816 *
7817 * SCIP comes along with a set of useful tools that allow to perform automated tests. The
7818 * following is a step-by-step guide from setting up the test environment for evaluation and
7819 * customization of test runs.
7820 *
7821 *
7822 * @section SETUP Setting up the test environment
7823 *
7824 * At first you should create a file listing all problem instances that should be part of the test.
7825 * This file has to be located in the the directory <code>scip/check/testset/</code>
7826 * and has to have the file extension <code>.test</code>, e.g., <code>testrun.test</code>,
7827 * in order to be found by the <code>scip/check/check.sh</code> script.
7828 * \n
7829 * All test problems can be listed in the <code>test</code>-file by a relative path,
7830 * e.g., <code>../../problems/instance1.lp</code> or absolute path, e.g., <code>/home/problems/instance2.mps</code>
7831 * in this file. Only one problem should be listed on every line (since the command <code>cat</code> is used to parse this file).
7832 * Note that these problems have to be readable for SCIP in order to solve them.
7833 * However, you can use different file formats.
7834 *
7835 * Optionally, you can provide a solution file in the <code>scip/check/testset/</code> directory containing
7836 * known information about the feasibility and the best known objective values for the test instances.
7837 * SCIP can use these values to verify the results. The file has to have the same basename as the
7838 * <code>.test</code>-file, i.e., in our case <code>testrun.solu</code>. One line can only contain
7839 * information about one test instance. A line has to start with the type of information given:
7840 *
7841 * - <code>=opt=</code> stating that a problem name with an optimal objective value follows
7842 * - <code>=best=</code> stating that a problem name with a best know objective value follows
7843 * - <code>=inf=</code> stating that a problem name follows which is infeasible
7844 *
7845 * With these information types you can encode for an instance named <code>instance1.lp</code> the following
7846 * information:
7847 * - The instance has a known optimal (objective) value of 10.
7848 * \code
7849 * =opt= instance1 10
7850 * \endcode
7851 * - The instance has a best known solution with objective value 15.
7852 * \code
7853 * =best= instance1 15
7854 * \endcode
7855 * - The instance is feasible (but has no objective function or we don't know a solution value)
7856 * \code
7857 * =feas= instance1
7858 * \endcode
7859 * - The instance is infeasible.
7860 * \code
7861 * =inf= instance1
7862 * \endcode
7863 *
7864 * If you don't know whether the instance is feasible or not (so the status is unknown),
7865 * you can omit the instance in the <code>solu</code>-file or write
7866 * \code
7867 * =unkn= instance1
7868 * \endcode
7869 *
7870 * <b>Note that in all lines the file extension of the file name is omitted.</b>
7871 * \n
7872 * See the files <code>scip/check/testset/short.test</code> and <code>scip/check/testset/short.solu</code>
7873 * for an example of a <code>test</code>-file and its corresponding <code>solu</code>-file.
7874 *
7875 *
7876 *
7877 * @section STARTING Starting a test run
7878 *
7879 *
7880 * \code
7881 * make TEST=testrun test
7882 * \endcode
7883 *
7884 * in the SCIP root directory. Note that <code>testrun</code> is exactly the basename of our
7885 * <code>test</code>-file (<code>testrun.test</code>). This will cause SCIP to solve our test instances
7886 * one after another and to create various output files (see \ref EVAL).
7887 *
7888 *
7889 * @section EVAL Evaluating a test run
7890 *
7891 * During computation, SCIP automatically creates the directory <code>scip/check/results/</code>
7892 * (if it does not already exist) and stores the following output files there.
7893 *
7894 * \arg <code>*.out</code> - output of <code>stdout</code>
7895 * \arg <code>*.err</code> - output of <code>stderr</code>
7896 * \arg <code>*.set</code> - copy of the used settings file
7897 *
7898 * \arg <code>*.res</code> - ASCII table containing a summary of the computational results
7899 * \arg <code>*.tex</code> - TeX table containing a summary of the computational results
7900 * \arg <code>*.pav</code> - <a href="http://www.gamsworld.org/performance/paver/">PAVER</a> output
7901 *
7902 * The last three files in the above list, i.e., the files containing a summary of the computational results,
7903 * can also be generated manually. Therefore the user has to call the <code>evalcheck.sh</code> script in the
7904 * @c check directory with the corresponding @c out file as argument. For example, this may be useful if the user stopped the
7905 * test before it was finished, in which case the last three files will not be automatically generated by SCIP.
7906 *
7907 * The last column of the ASCII summary table contains the solver status. We distinguish the following statuses: (in order of priority)
7908 *
7909 * \arg abort: solver broke before returning solution
7910 * \arg fail: solver cut off a known feasible solution (value of the <code>solu</code>-file is beyond the dual bound;
7911 * especially if problem is claimed to be solved but solution is not the optimal solution)
7912 * <b>or</b> if a final solution check revealed a violation of one of the original constraints.
7913 * \arg ok: solver solved problem with the value in solu-file
7914 * \arg solved: solver solved problem which has no (optimal) value in solu-file (since we here cannot detect the direction
7915 * of optimization, it is possible that a solver claims an optimal solution which contradicts a known feasible solution)
7916 * \arg better: solver found solution better than known best solution (or no solution was noted in the <code>solu</code>-file so far)
7917 * \arg gaplimit, sollimit: solver reached gaplimit or limit of number of solutions (at present: only in SCIP)
7918 * \arg timeout: solver reached any other limit (like time or nodes)
7919 * \arg unknown: otherwise
7920 *
7921 * Additionally the <code>evalcheck.sh</code> script can generate a <code>solu</code>-file by calling
7922 * \code
7923 * ./evalcheck.sh writesolufile=1 NEWSOLUFILE=<solu-file> <out-file>
7924 * \endcode
7925 * where <code><solu-file></code> denotes the filename of the new file where the solutions shall be
7926 * (and <code><out-file></code> denotes the output (<code>.out</code>) files to evaluate).
7927 *
7928 * Another feature can be enabled by calling:
7929 * \code
7930 * ./evalcheck.sh printsoltimes=1 ...
7931 * \endcode
7932 * The output has two additional columns containing the solving time until the first and the best solution was found.
7933 *
7934 *
7935 * @b Note: The @em basename of all these files is the same and has the following structure
7936 * which allows us to reconstruct the test run:
7937 *
7938 * \code
7939 * check.<test name>.<binary>.<machine name>.<setting name>
7940 * \endcode
7941 *
7942 * \arg <<code>test name</code>> indicates the name of the the test file, e.g., <code>testrun</code>
7943 * \arg <<code>binary</code>> defines the used binary, e.g., <code>scip-3.2.0.linux.x86_64.gnu.opt.spx</code>
7944 * \arg <<code>machine name</code>> tells the name of the machine, e.g., <code>mycomputer</code>
7945 * \arg <<code>setting name</code>> denotes the name of the used settings, e.g., <code>default</code>
7946 * means the (SCIP) default settings were used
7947 *
7948 * Using the examples out of the previous listing the six file names would have the name:
7949 *
7950 * \code
7951 * check.testrun.scip-1.1.0.linux.x86.gnu.opt.spx.mycomputer.default.<out,err,set,res,tex,pav>
7952 * \endcode
7953 *
7954 *
7955 * @section USING Using customized setting files
7956 *
7957 * It is possible to use customized settings files for the test run instead of testing SCIP with default settings.
7958 * These have to be placed in the directory <code>scip/settings/</code>.
7959 *
7960 * @b Note: Several common user parameters such as, e.g., the time limit and node limit parameters,
7961 * <b>cannot</b> be controlled by the settings file, whose specifications would be overwritten
7962 * by optional command line arguments to the <code>make test</code> command, see @ref ADVANCED
7963 * for a list of available advanced testing options that have to be specified from the command line.
7964 *
7965 * @b Note: Accessing settings files in subfolders of the @c settings directory is currently not supported.
7966 *
7967 * To run SCIP with a custom settings file, say for example <code>fast.set</code>, we call
7968 *
7969 * \code
7970 * make TEST=testrun SETTINGS=fast test
7971 * \endcode
7972 *
7973 * in the SCIP root directory. It is possible to enter a list of settings files as a double-quoted,
7974 * comma-separated list of settings names as <code>fast</code> above, i.e. <code>SETTINGS="fast,medium,slow"</code>
7975 * will invoke the solution process for every instance with the three settings <code>fast.set, medium.set, slow.set</code>
7976 * before continuing with the next instance from the <code>.test</code>-file. This may come in handy if the
7977 * whole test runs for a longer time and partial results are already available.
7978 *
7979 *
7980 * @section ADVANCED Advanced options
7981 *
7982 * We can further customize the test run by specifying the following options in the <code>make</code> call:
7983 *
7984 * \arg <code>CONTINUE</code> - continue the test run if it was previously aborted [default: "false"]
7985 * \arg <code>DISPFREQ</code> - display frequency of the output [default: 10000]
7986 * \arg <code>FEASTOL</code> - LP feasibility tolerance for constraints [default: "default"]
7987 * \arg <code>LOCK</code> - should the test run be locked to prevent other machines from performing the same test run [default: "false"]
7988 * \arg <code>MAXJOBS=n</code> - run tests on 'n' cores in parallel. Note that several instances are solved in parallel, but
7989 * only one thread is used per job (parallelization is not that easy) [default: 1]
7990 * \arg <code>MEM</code> - memory limit in MB [default: 6144]
7991 * \arg <code>NODES</code> - node limit [default: 2100000000]
7992 * \arg <code>TIME</code> - time limit for each test instance in seconds [default: 3600]
7993 * \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]
7994 * \arg <code>THREADS</code> - the number of threads used for solving LPs, if the linked LP solver supports multithreading [default: 1]
7995 * \arg <code>VALGRIND</code> - run valgrind on the SCIP binary; errors and memory leaks found by valgrind are reported as fails [default: "false"]
7996 *
7997 *
7998 * @section COMPARE Comparing test runs for different settings
7999 *
8000 * Often test runs are performed on the basis of different settings. In this case, it is useful to
8001 * have a performance comparison. For this purpose, we can use the <code>allcmpres.sh</code> script in
8002 * the @c check directory.
8003 *
8004 * Suppose, we performed our test run with two different settings, say <code>fast.set</code> and
8005 * <code>slow.set</code>. Assuming that all other parameters (including the SCIP binary), were the same,
8006 * we may have the following <code>res</code>-files in the directory <code>scip/check/results/</code>
8007 *
8008 * \code
8009 * check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.fast.res
8010 * check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.slow.res
8011 * \endcode
8012 *
8013 * For a comparison of both computations, we simply call
8014 *
8015 * \code
8016 * allcmpres.sh results/check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.fast.res \
8017 * results/check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.slow.res
8018 * \endcode
8019 *
8020 * in the @c check directory. This produces an ASCII table on the console that provide a detailed
8021 * performance comparison of both test runs. Note that the first <code>res</code>-file serves as reference
8022 * computation. The following list explains the output.
8023 * (The term "solver" can be considered as the combination of SCIP with a specific setting file.)
8024 *
8025 * \arg <code>Nodes</code> - Number of processed branch-and-bound nodes.
8026 * \arg <code>Time</code> - Computation time in seconds.
8027 * \arg <code>F</code> - If no feasible solution was found, then '#', empty otherwise.
8028 * \arg <code>NodQ</code> - Equals Nodes(i) / Nodes(0), where 'i' denotes the current solver and '0' stands for the reference solver.
8029 * \arg <code>TimQ</code> - Equals Time(i) / Time(0).
8030 * \arg <code>bounds check</code> - Status of the primal and dual bound check.
8031 *
8032 * \arg <code>proc</code> - Number of instances processed.
8033 * \arg <code>eval</code> - Number of instances evaluated (bounds check = "ok", i.e., solved to optimality
8034 * within the time and memory limit and result is correct). Only these instances are used in the calculation
8035 * of the mean values.
8036 * \arg <code>fail</code> - Number of instances with bounds check = "fail".
8037 * \arg <code>time</code> - Number of instances with timeout.
8038 * \arg <code>solv</code> - Number of instances correctly solved within the time limit.
8039 * \arg <code>wins</code> - Number of instances on which the solver won (i.e., the
8040 * solver was at most 10% slower than the fastest solver OR had the best
8041 * primal bound in case the instance was not solved by any solver within
8042 * the time limit).
8043 * \arg <code>bett</code> - Number of instances on which the solver was better than the
8044 * reference solver (i.e., more than 10% faster).
8045 * \arg <code>wors</code> - Number of instances on which the solver was worse than the
8046 * reference solver (i.e., more than 10% slower).
8047 * \arg <code>bobj</code> - Number of instances on which the solver had a better primal
8048 * bound than the reference solver (i.e., a difference larger than 10%).
8049 * \arg <code>wobj</code> - Number of instances on which the solver had a worse primal
8050 * bound than the reference solver (i.e., a difference larger than 10%).
8051 * \arg <code>feas</code> - Number of instances for which a feasible solution was found.
8052 * \arg <code>gnodes</code> - Geometric mean of the processed nodes over all evaluated instances.
8053 * \arg <code>shnodes</code> - Shifted geometric mean of the processed nodes over all evaluated instances.
8054 * \arg <code>gnodesQ</code> - Equals nodes(i) / nodes(0), where 'i' denotes the current
8055 * solver and '0' stands for the reference solver.
8056 * \arg <code>shnodesQ</code> - Equals shnodes(i) / shnodes(0).
8057 * \arg <code>gtime</code> - Geometric mean of the computation time over all evaluated instances.
8058 * \arg <code>shtime</code> - Shifted geometric mean of the computation time over all evaluated instances.
8059 * \arg <code>gtimeQ</code> - Equals time(i) / time(0).
8060 * \arg <code>shtimeQ</code> - Equals shtime(i) / shtime(0).
8061 * \arg <code>score</code> - N/A
8062 *
8063 * \arg <code>all</code> - All solvers.
8064 * \arg <code>optimal auto settings</code> - Theoretical result for a solver that performed 'best of all' for every instance.
8065 * \arg <code>diff</code> - Solvers with instances that differ from the reference solver in the number of
8066 * processed nodes or in the total number of simplex iterations.
8067 * \arg <code>equal</code> - Solvers with instances whose number of processed nodes and total number of
8068 * simplex iterations is equal to the reference solver (including a 10% tolerance) and where no timeout
8069 * occured.
8070 * \arg <code>all optimal</code> - Solvers with instances that could be solved to optimality by
8071 * <em>all</em> solvers; in particular, no timeout occurred.
8072 *
8073 * Since this large amount of information is not always needed, one can generate a narrower table by calling:
8074 * \code
8075 * allcmpres.sh short=1 ...
8076 * \endcode
8077 * where <code>NodQ</code>, <code>TimQ</code> and the additional comparison tables are omitted.
8078 *
8079 * If the <code>res</code>-files were generated with the parameter <code>printsoltimes=1</code>
8080 * we can enable the same feature here as well by calling:
8081 * \code
8082 * allcmpres.sh printsoltimes=1 ...
8083 * \endcode
8084 * As in the evaluation, the output contains the two additional columns of the solving time until the first and the best solution was found.
8085 *
8086 * @section STATISTICS Statistical tests
8087 *
8088 * The \c allcmpres script also performs two statistical tests for comparing different settings: For deciding whether
8089 * more feasible solutions have been found or more instances have been solved to optimality or not, we use a McNemar
8090 * test. For comparing the running time and number of nodes, we use a variant of the Wilcoxon signed rank test. A
8091 * detailed explanation can be found in the PhD thesis of Timo Berthold (Heuristic algorithms in global MINLP solvers).
8092 *
8093 * @subsection McNemar McNemar test
8094 *
8095 * Assume that we compare two settings \c S1 and \c S2 with respect to the number of instances solved to optimality
8096 * within the timelimit. The null hypothesis would be "Both settings lead to an equal number of instances being solved
8097 * to optimality", which we would like to disprove. Let \f$n_1\f$ be the number of instances solved by setting \c S1
8098 * 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
8099 * McNemar test statistic is
8100 * \f[
8101 * \chi^2 = \frac{(n_1 - n_2)^2}{n_1 + n_2}.
8102 * \f]
8103 * Under the null hypothesis, \f$\chi^2\f$ is chi-squared distributed with one degree of freedom. This allows to compute
8104 * a \f$p\f$-value as the probability for obtaining a similar or even more extreme result under the null hypothesis.
8105 * More explicitly, \c allcmpres uses the following evaluation:
8106 * - \f$0.05 < p\f$: The null hypothesis is accepted (marked by "X").
8107 * - \f$0.005 < p \leq 0.05\f$: The null hypothesis might be false (marked by "!").
8108 * - \f$0.0005 < p \leq 0.005\f$: The null hypothesis can be false (marked by "!!").
8109 * - \f$p \leq 0.0005\f$: The null hypothesis is very likely false (marked by "!!!").
8110 *
8111 * As an example consider the following output:
8112 * \code
8113 * McNemar (feas) x2 0.0000, 0.05 < p X
8114 * McNemar (opt) x2 6.0000, p ~ (0.005, 0.05] !
8115 * \endcode
8116 * Here, \c x2 represents \f$\chi^2\f$.
8117 *
8118 * In this case, the test with respect to the number of found feasible solutions is irrelevant, since their number is
8119 * equal. In particular, the null hypothesis gets accepted (i.e., there is no difference in the settings - this is
8120 * marked by "X").
8121 *
8122 * With respect to the number of instances solved to optimality within the timelimit, we have that \f$0.005 < p <=
8123 * 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
8124 * settings perform differently; this is marked by "!". In the concrete case, we have 230 instances, all of which are
8125 * solved by setting \c S2, but only 224 by setting \c S1.
8126 *
8127 * @subsection Wilcoxon Wilcoxon signed rank test
8128 *
8129 * Assume that we compare two settings \c S1 and \c S2 with respect to their solution times (within the time limit). We
8130 * generate a sorted list of the ratios of the run times, where ratios that are (absolutely or relatively) within 1\%
8131 * of 1.0 are discarded, and ratios between 0.0 and 0.99 are replaced with their negative inverse in order to
8132 * obtain a symmetric distribution for the ratios around the origin.
8133 * We then assign ranks 1 to \c N to the remaining \c N data points in nondecreasing
8134 * order of their absolute ratio. This yields two groups \c G1
8135 * 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
8136 * setting \c S1 is faster). Then the sums of the ranks in groups \c G1 and \c G2 are computed, yielding values \c R1
8137 * and \c R2, respectively.
8138 *
8139 * The Wilcoxon test statistic is then
8140 * \f[
8141 * z = \frac{\min(R1, R2) - \frac{N(N+1)}{4}}{\sqrt{\frac{N(N+1)(2N+1)}{24}}},
8142 * \f]
8143 * which we assume to be (approximately) normally distributed (with zero mean) and allows to compute the probability
8144 * \f$p\f$ that one setting is faster than the other. (Note that for \f$N \leq 60\f$, we apply a correction by
8145 * subtracting 0.5 from the numerator).
8146 *
8147 * As an example consider the following output:
8148 * \code
8149 * Wilcoxon (time) z -0.1285, 0.05 <= p X
8150 * Wilcoxon (nodes) z -11.9154, p < 0.0005 !!!
8151 * \endcode
8152 * While the \f$z\f$-value is close to zero for the run time, it is extremely negative regarding the solving nodes. This latter
8153 * 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
8154 * nodes than setting \c S2 is negligible (this null hypothesis is rejected - marked by "!!!").
8155 *
8156 * However, the null hypothesis is not rejected with respect to the run time. In the concrete case, setting \c S1 has a
8157 * 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
8158 * 0.88. Still - the null hypothesis is not rejected.
8159 *
8160 * @section SOLVER Testing and Evaluating using GAMS
8161 *
8162 * Analogously to the target <code>test</code> there is another target to run automated tests with <a href="http://www.gams.com/">gams</a>
8163 * \code
8164 * make testgams GAMSSOLVER=xyz
8165 * \endcode
8166 * For this target, the option GAMSSOLVER has to be given to specify the name of a GAMS solver to run, e.g. GAMSSOLVER=SCIP.
8167 * Additional advanced options specific to this target are:
8168 * GAMS to specify the GAMS executable (default: gams),
8169 * GAP to specify a gap limit (default: 0.0),
8170 * CLIENTTMPDIR to specify a directory where GAMS should put its scratch files (default: /tmp),
8171 * 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).
8172 * The following options are NOT supported (and ignored): DISPFREQ, FEASTOL, LOCK.
8173 * 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).
8174 *
8175 * Note: This works only if the referred programs are installed globally on your machine.
8176 *
8177 * The above options like <code>TIME</code> are also available for gams.
8178 *
8179 * After the testrun there should be an <code>.out</code>, an <code>.err</code> and a <code>.res</code> file
8180 * with the same basename as described above.
8181 *
8182 * Furthermore you can also use the script <code>allcmpres.sh</code> for comparing results.
8183 *
8184 * @section PYTHON Testing using PySCIPOpt
8185 *
8186 * To run a python script that uses PySCIPOpt with <code>make test</code> or <code>make testcluster</code>, one has to
8187 * specify the python code to execute with the option <code>EXECUTABLE=/full/path/to/python-script.py</code>.
8188 * Note that <code>python-script.py</code> must be an executable file.
8189 * In addition, one <b>must</b> specify which python it should run with the option <code>PYTHON=my-python</code>.
8190 * The reason for this is that one usually installs PySCIPOpt in a virtual environment, thus only the python of the
8191 * virtual environment will work with the python script.
8192 *
8193 * The scripts work in such a way that they pass information to SCIP like the setting files, the instance name, and some other options.
8194 * It is the responsability of the python script <code>python-script.py</code> to parse this information.
8195 * Thus, you need to modify your python script to read the setting files and the other options provided by the testing scripts.
8196 * An example of how to do this is provided in <code>scip/check/scip-runner.py</code>.
8197 * One should either modify <code>scip/check/scip-runner.py</code> or include the <code>build_model()</code> function
8198 * into your script to correctly read the options passed by the scripts.
8199 *
8200 * An example of how to run the tests is
8201 * \code
8202 * make test EXECUTABLE=/full/path/to/scip/check/scip-runner.py PYTHON=python
8203 * \endcode
8204 */
8205
8206/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
8207
8208/**@page COUNTER How to use SCIP to count/enumerate feasible solutions
8209 *
8210 * SCIP is capable of computing (count or enumerate) the number of feasible solutions of a given constraint integer
8211 * program. In case continuous variables are present, the number of feasible solutions for the projection to the
8212 * integral variables is counted/enumerated. This means, an assignment to the integer variables is counted if the
8213 * remaining problem (this is the one after fixing the integer variables w.r.t. to this assignment) is feasible.
8214 *
8215 * As a first step you have to load or create your problem in the usual way. In case of using the
8216 * interactive shell, you use the <code>read</code> command:
8217 *
8218 * <code>SCIP&gt; read &lt;file name&gt;</code>
8219 *
8220 * Afterwards you can count the number of feasible solution with the command <code>count</code>.
8221 *
8222 * <code>SCIP&gt; count</code>
8223 *
8224 * @note After completing the counting process, SCIP will terminate with status <tt>infeasible</tt>. This is intended
8225 * behavior, because SCIP counts solutions by the following internal mechanism. Each feasible solution that is found is
8226 * reported as infeasible to the SCIP core. This avoids that SCIP performs reductions based on the primal bound that
8227 * could cut off suboptimal feasible solutions, which would then be missing in the count. However, as a result, the
8228 * SCIP core has not found any feasible solutions during the search and reports status <tt>infeasible</tt>.
8229 *
8230 * By default, SCIP only counts the number of solutions but does not store (enumerate) them. If you are interested in
8231 * that see \ref COLLECTALLFEASEBLES.
8232 *
8233 * @note Since SCIP version 2.0.0 you do not have to worry about the impact of dual reductions anymore. These are
8234 * automatically turned off. The only thing you should switch off are restarts. These restarts can lead to a wrong
8235 * counting process. We recommend using the counting settings which can be set in the interactive shell as follows:
8236 *
8237 * <code>SCIP&gt; set emphasis counter</code>
8238 *
8239 * The SCIP callable library provides an interface method SCIPcount() which allows users to count the number of feasible
8240 * solutions to their problem. The method SCIPsetParamsCountsols(), which is also located in cons_countsols.h, loads the
8241 * predefined counting settings to ensure a safe count. The complete list of all methods that can be used for counting
8242 * via the callable library can be found in cons_countsols.h.
8243 *
8244 *
8245 * @section COUNTLIMIT Limit the number of solutions which should be counted
8246 *
8247 * It is possible to give a (soft) upper bound on the number solutions that should be counted. If this upper bound is
8248 * exceeded, SCIP will be stopped. The name of this parameter is <code>constraints/countsols/sollimit</code>. In
8249 * the interactive shell this parameter can be set as follows:
8250 *
8251 * <code>SCIP&gt; set constraints countsols sollimit 1000</code>
8252 *
8253 * In case you are using the callable library, this upper bound can be assigned by calling SCIPsetLongintParam() as follows:
8254 *
8255 * \code
8256 * SCIP_CALL( SCIPsetLongintParam( scip, "constraints/countsols/sollimit", 1000) );
8257 * \endcode
8258 *
8259 *
8260 * The reason why this upper bound is soft comes from the fact that, by default, SCIP uses a technique called unrestricted
8261 * subtree detection. Using this technique it is possible to detect several solutions at once. Therefore, it can happen
8262 * that the solution limit is exceeded before SCIP is stopped.
8263 *
8264 * @section COLLECTALLFEASEBLES Collect all feasible solutions
8265 *
8266 * Per default SCIP only counts all feasible solutions. This means, these solutions are not stored. If you switch the
8267 * parameter <code>constraints/countsols/collect</code> to TRUE (the default value is FALSE) the detected solutions are
8268 * stored. Changing this parameter can be done in the interactive shell
8269 *
8270 * <code>SCIP&gt; set constraints countsols collect TRUE</code>
8271 *
8272 * as well as via the callable library
8273 *
8274 * \code
8275 * SCIP_CALL( SCIPsetBoolParam( scip, "constraints/countsols/collect", TRUE) );
8276 * \endcode
8277 *
8278 * @note The solution which are collected are stored w.r.t. the active variables. These are the variables which got not
8279 * removed during presolving.
8280 *
8281 * In case you are using the interactive shell you can write all collected solutions to a file as follows
8282 *
8283 * <code>SCIP&gt; write allsolutions &lt;file name&gt;</code>
8284 *
8285 * In that case the sparse solutions are unrolled and lifted back into the original variable space.
8286 *
8287 * The callable library provides a method which gives access to all collected sparse solutions. That is,
8288 * SCIPgetCountedSparseSolutions(). The sparse solutions you get are defined w.r.t. active variables. To get solutions
8289 * w.r.t. to the original variables. You have to do two things:
8290 *
8291 * -# unroll each sparse solution
8292 * -# lift each solution into original variable space by extending the solution by those variable which got removed
8293 * during presolving
8294 *
8295 * The get the variables which got removed during presolving, you can use the methods SCIPgetFixedVars() and
8296 * SCIPgetNFixedVars(). The method SCIPgetProbvarLinearSum() transforms given variables, scalars and constant to the
8297 * corresponding active variables, scalars and constant. Using this method for a single variable gives a representation
8298 * for that variable w.r.t. the active variables which can be used to compute the value for the considered solution (which
8299 * is defined w.r.t. active variables).
8300 *
8301 * For that complete procedure you can also check the source code of
8302 * \ref SCIP_DECL_DIALOGEXEC(SCIPdialogExecWriteAllsolutions) "SCIPdialogExecWriteAllsolutions()" cons_countsols.c which
8303 * does exactly that.
8304 *
8305 *
8306 * @section COUNTOPTIMAL Count number of optimal solutions
8307 *
8308 * If you are interested in counting the number of optimal solutions, this can be done with SCIP using the
8309 * <code>count</code> command by applying the following steps:
8310 *
8311 * -# Solve the original problem to optimality and let \f$c^*\f$ be the optimal value
8312 * -# Added the objective function as constraint with left and right hand side equal to \f$c^*\f$
8313 * -# load the adjusted problem into SCIP
8314 * -# use the predefined counting settings
8315 * -# start counting the number of feasible solutions
8316 *
8317 * If you do this, SCIP will collect all optimal solutions of the original problem.
8318 *
8319 */
8320
8321/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
8322
8323/** @page SYMMETRY How to use symmetry handling in SCIP
8324 *
8325 * Symmetry handling is an important feature of SCIP that allows to discard symmetric subproblems from the
8326 * branch-and-bound tree, and thus, can substantially reduce the running time. To handle symmetries, SCIP
8327 * automatically detects symmetries and then applies (combinations of) symmetry handling methods.
8328 *
8329 * @section SYMDETECT Symmetry detection
8330 *
8331 * In a purely integer linear setting
8332 * \f[
8333 * \max \{ c^{\top} x : Ax \leq b,\; x \in \mathbb{Z}^n \},
8334 * \f]
8335 * a symmetry is a permutation \f$\gamma\f$ of \f$\{1,\dots,n\}\f$ that acts on vector \f$x\f$ by
8336 * permuting its coordinates via \f$\gamma(x) = (x_{\gamma^{-1}(1)}, \dots, x_{\gamma^{-1}(n)})\f$
8337 * such that
8338 *
8339 * -# \f$\gamma\f$ leaves the objective invariant, i.e., \f$c^{\top}x = c^{\top}\gamma(x)\f$, and
8340 * -# \f$\gamma\f$ maps feasible solutions onto feasible solutions, i.e., \f$Ax \leq b\f$ if and only
8341 * if \f$A\gamma(x) \leq b\f$.
8342 *
8343 * Since this definition depends on the feasible region of the integer program, which is unknown
8344 * in general, SCIP only computes symmetries that leave the formulation of the optimization problem
8345 * invariant. To detect such formulation symmetries, SCIP builds an auxiliary colored graph whose
8346 * color-preserving automorphisms correspond to symmetries of the integer program. The symmetries of
8347 * the graph, and thus of the integer program, are then computed by an external graph automorphism
8348 * library that needs to be linked to SCIP. Currently, SCIP ships with two such libraries: The graph
8349 * automorphism library bliss is the basic workhorse to detect symmetries. Moreover, one can use
8350 * sassy, a graph symmetry preprocessor which passes the preprocessed graphs to bliss and is the
8351 * current default.
8352 *
8353 * @note To detect symmetries, SCIP needs to be built with sassy/bliss, which can be achieved
8354 * by using the options <code>SYM=sassy</code> and <code>-DSYM=sassy</code> in the Makefile and CMake
8355 * system, respectively.
8356 *
8357 * Besides purely integer linear problems, SCIP also supports symmetry detection for general
8358 * constraint mixed-integer programs containing most of the constraint types that can be handled
8359 * by SCIP. In particular, symmetries of mixed-integer nonlinear problems can be detected.
8360 *
8361 * @subsection SYMPROCESS Processing symmetry information
8362 *
8363 * After symmetries have been computed, SCIP has access to a list \f$\gamma_1,\dots,\gamma_m\f$ of
8364 * permutations that generate a group \f$\Gamma\f$ of symmetries of the optimization problem. That
8365 * is, SCIP has not access to all permutations in \f$\Gamma\f$, but only a set of generators. Based
8366 * on these generators, SCIP analyzes the group \f$\Gamma\f$ and checks whether it can be split into
8367 * independent factors. That is, whether there exist subgroups \f$\Gamma_1,\dots,\Gamma_k\f$ of
8368 * \f$\Gamma\f$ that act on pairwise independent sets of variables such that \f$\bigcup_{i=1}^k \Gamma_i = \Gamma\f$.
8369 * In this case, SCIP can handle the symmetries of the different subgroups independently. In particular,
8370 * different subgroups can be treated by different symmetry handling methods.
8371 *
8372 * @section SYMMETHODS Symmetry handling methods
8373 *
8374 * To handle symmetries, SCIP uses three different classes of methods, which we detail below.
8375 *
8376 * @subsection SYMCONSS Symmetry handling constraints
8377 *
8378 * SCIP contains three constraint handlers for handling symmetries of binary variables: the symresack,
8379 * orbisack, and orbitope constraint handler. Given a symmetry \f$\gamma\f$,
8380 * the symresack constraint handler enforces that a solution vector \f$x\f$ is not lexicographically
8381 * smaller than its image \f$\gamma(x)\f$. This constraint is enforced by a propagation algorithm
8382 * and separating inequalities. Moreover, given the disjoint cycle decomposition of \f$\gamma\f$,
8383 * SCIP checks, for each cycle of \f$\gamma\f$, whether all variables in the cycle are contained
8384 * in set packing or partitioning constraints. If this is the case, specialized inequalities can
8385 * be separated.
8386 *
8387 * In case the permutation \f$\gamma\f$ is an involution, i.e., \f$\gamma(\gamma(x)) = x\f$,
8388 * specialized separation and propagation algorithms can be used, which are implemented in the
8389 * orbisack constraint handler. For orbisack constraints, also facet-defining inequalities of the
8390 * convex hull of all binary points \f$x\f$ being not lexicographically smaller than \f$\gamma(x)\f$
8391 * can be separated. Since the coefficients in these inequalities grow exponentially large which might
8392 * cause numerical instabilities, the separation of these inequalities is disabled by default, but can be
8393 * enabled via the parameter <code>constraints/orbisack/orbiSeparation</code>. Furthermore, to avoid
8394 * numerical instabilities, the parameter <code>constraints/orbisack/coeffbound</code> controls the
8395 * maximum absolute value of a coefficient in separated facet-defining inequalities.
8396 *
8397 * Finally, the orbitope constraint handler is able to handle symmetries of special symmetric groups \f$\Gamma\f$.
8398 * For orbitopes to be applicable, the affected variables need to be arranged in a matrix \f$X\f$ such that
8399 * the symmetries in \f$\Gamma\f$ permute the columns of \f$X\f$. Symmetries are then handled by orbitope
8400 * constraints by enforcing to only compute solution matrices \f$X\f$ whose columns are sorted lexicographically
8401 * non-increasingly. To this end, a propagation algorithm is used and inequalities are separated. In case
8402 * the variables of each row of the matrix \f$X\f$ are contained in a set packing or partitioning constraint,
8403 * specialized propagation and separation routines are used.
8404 *
8405 * @subsection SYMOF Orbital fixing
8406 *
8407 * Orbital fixing is a propagation algorithm that derives fixings of binary variables based on
8408 * already fixed variables. These fixings remove feasible solutions of the problem, while it is guaranteed
8409 * that at least one symmetric solution remains feasible. The reductions found by orbital fixing
8410 * are derived from the branching decisions. Thus, as SCIP might restart the branch-and-bound process,
8411 * which removes previously made branching decisions, we need to make sure that correct reductions are
8412 * found after a restart. This can be guaranteed by either disabling orbital fixing after a restart
8413 * or recomputing symmetries. In SCIP, this is controlled via the parameter
8414 * <code>propagating/symmetry/recomputerestart</code>. If it takes value 0, symmetries are not
8415 * recomputed and orbital fixing is disabled; a value of 1 means that symmetries are always
8416 * recomputed; if it has value 2, symmetries are only recomputed if orbital fixing has found a
8417 * reduction before the restart.
8418 *
8419 * @subsection SYMSST SST cuts
8420 *
8421 * The Schreier-Sims table (SST) is a table that contains certain information about symmetry groups
8422 * and can be used, among others, to derive symmetry handling inequalities. The corresponding SST cuts
8423 * are symmetry handling inequalities that are defined iteratively in rounds \f$r = 1,\dots,R\f$.
8424 * In each round \f$r\f$, a leader variable \f$\ell_r\f$ is selected and the group
8425 * \f$\Gamma_r = \{ \gamma \in \Gamma : \gamma(\ell_i) = \ell_i \text{ for all } i = 1,\dots,r-1\}\f$
8426 * is considered. Then, the symmetry handling inequalities of round \f$r\f$ are defined as
8427 * \f$x_{\ell_r} \geq x_j\f$ for all \f$j \in \{\gamma(i) : i \in \{1,\dots,n\}\}\f$.
8428 * The latter set is called the orbit of leader \f$\ell_r\f$.
8429 *
8430 * SST cuts admit many degrees of freedom. In particular, they are not limited to binary variables
8431 * but can be used for arbitrary variable types. A user can gain control over the selection process of
8432 * SST cuts via several parameters. For instance,
8433 *
8434 * - <code>sstleadervartype</code> is a bitset encoding the variable types of leaders: the 1-bit models binary,
8435 * the 2-bit integer, the 4-bit implicit integer, and the 8-bit continuous variables. That is, a value
8436 * of 9 models that the leader can be a binary or continuous variable.
8437 * - <code>sstleaderrule</code> ranges from 0 to 2 and models whether a leader is the first variable in
8438 * its orbit, the last variable in its orbit, or a variable with most conflicts with other variables in
8439 * the orbit, respectively.
8440 * - <code>ssttiebreakrule</code> ranges from 0 to 2 and models whether an orbit of minimum size, maximum
8441 * size or with most variables being in conflict to the leader is selected, respectively.
8442 * - <code>sstmixedcomponents</code> whether SST cuts are also applied if a symmetries do not only affect
8443 * variables of a single type.
8444 * - <code>sstaddcuts</code> whether SST cuts are added to the problem. If no cuts are added, only
8445 * binary variables might be fixed to 0 if they are in conflict with the leader.
8446 *
8447 * @subsection SYMMETHODSELECT Selecting symmetry handling methods
8448 *
8449 * The three symmetry handling methods explained above can be enabled and disabled via the parameter
8450 * <code>misc/usesymmetry</code>, which encodes the enabled methods via a bitset that ranges between 0
8451 * and 7: the 1-bit encodes symmetry handling constraints, the 2-bit encodes orbital fixing, and the
8452 * 4-bit encodes SST cuts. For example, <code>misc/usesymmetry = 3</code> enables symmetry handling
8453 * constraints and orbital fixing, whereas <code>misc/usesymmetry = 0</code> disables symmetry handling.
8454 * In the following, we explain how the combination of different symmetry handling methods works.
8455 *
8456 * The default strategy of SCIP is to handle symmetries via the bitset value 7, i.e., symmetry handling
8457 * constraints, orbital fixing, and SST cuts are enabled. To make sure that the different methods are
8458 * compatible, the following steps are carried out:
8459 *
8460 * -# SCIP determines independent subgroups \f$\Gamma_1,\dots,\Gamma_k\f$ as described in \ref SYMPROCESS.
8461 * Then, for each subgroup \f$\Gamma_i\f$, different symmetry handling methods can be applied.
8462 * -# For each subgroup \f$\Gamma_i\f$, a heuristic is called that checks whether orbitopes are applicable
8463 * to handle the entire subgroup. If yes, this subgroup is handled by orbitopes and no other
8464 * symmetry handling methods.
8465 * -# Otherwise, if parameter <code>propagating/symmetry/detectsubgroups</code> is <code>TRUE</code>, a
8466 * heuristic is called to detect whether "hidden" orbitopes are present. That is, whether some but not
8467 * all symmetries of \f$\Gamma_i\f$ can be handled by orbitopes. If sufficiently many symmetries can
8468 * be handled by orbitopes, orbitopes are applied and, if parameter <code>propagating/symmetry/addweaksbcs</code>
8469 * is TRUE, some compatible SST cuts are added, too. Besides this, no further symmetry handling methods
8470 * are applied for \f$\Gamma_i\f$.
8471 * -# Otherwise, if the majority of variables affected by \f$\Gamma_i\f$ are non-binary, SST cuts are applied
8472 * to handle \f$\Gamma_i\f$. No further symmetry handling methods are applied for \f$\Gamma_i\f$.
8473 * -# Finally, if none of the previous methods has been used to handle \f$\Gamma_i\f$, orbital fixing is
8474 * used.
8475 *
8476 * @note If one of the previous methods is disabled via <code>misc/usesymmetry</code>, it might be possible
8477 * that not all symmetries are handled. For instance, if orbital fixing is disabled and neither SST cuts
8478 * nor orbitopes are applied to handle \f$\Gamma_i\f$, the parameter <code>propagating/symmetry/addsymresacks</code>
8479 * needs to be set to <code>TRUE</code> to handle the symmetries of \f$\Gamma_i\f$. If this parameter is
8480 * <code>TRUE</code>, then orbisack/symresack constraints are also applied to subgroups that are handled
8481 * via hidden orbitopes or SST cuts (if these cuts are applied for binary variables).
8482 *
8483 *
8484 * @subsection SYMTIMING Controlling the timing of symmetry computation
8485 *
8486 * Since presolving might both remove and introduce formulation symmetries, the timing of computing symmetries
8487 * can be changed via the parameters <code>propagating/symmetry/addconsstiming</code> and
8488 * <code>propagating/symmetry/ofsymcomptiming</code> depending on whether symmetry handling constraints/SST cuts
8489 * and orbital fixing are applied, respectively. If both are applied, <code>propagating/symmetry/addconsstiming</code>
8490 * is dominant. Both parameters take values 0, 1, or 2, corresponding to computing symmetries before presolving,
8491 * during presolving, or when the symmetry handling methods are applied first, respectively. For the constraint-based
8492 * approach, the latter means at the end of presolving; for orbital fixing, after the first branching decision.
8493 *
8494 * If a restart occurs, symmetry handling constraints and SST cuts can be inherited to the new run. Since orbital
8495 * fixing depends on the branching history, which is not available after a restart anymore, symmetries might needed
8496 * to be recomputed. This is controlled via the parameter <code>propagating/symmetry/recomputerestart</code>, which
8497 * takes values 0, 1, or 2, corresponding to never recomputing symmetries (i.e., disabling orbital fixing after a
8498 * restart), always recompute symmetries, or only recomputing symmetries if orbital fixing found a reduction in
8499 * the previous run, respectively.
8500 */
8501
8502/**@page LICENSE License
8503 *
8504 * \verbinclude LICENSE
8505 */
8506
8507/**@page FAQ Frequently Asked Questions (FAQ)
8508 * \htmlinclude faq/faq.inc
8509 */
8510
8511
8512/**@page PARAMETERS List of all SCIP parameters
8513 *
8514 * This page list all parameters of the current SCIP version. This list can
8515 * easily be generated by SCIP via the interactive shell using the following command:
8516 *
8517 * <code>SCIP&gt; set save &lt;file name&gt;</code>
8518 *
8519 * or via the function call:
8520 *
8521 * <code>SCIP_CALL( SCIPwriteParams(scip, &lt;file name&gt;, TRUE, FALSE) );</code>
8522 *
8523 * \verbinclude parameters.set
8524 */
8525
8526/**@page INTERFACES Interfaces
8527 *
8528 * There are several ways of accessing the \SCIP Optimization Suite from other software packages or programming
8529 * platforms.
8530 *
8531 *
8532 * @section FILEFORMATS File formats
8533 *
8534 * The easiest way to load a problem into SCIP is via an input file, given in a format that SCIP can parse directly,
8535 * see \ref SHELL "the tutorial on how to use the interactive shell".
8536 * \SCIP is capable of reading more than ten different file formats, including formats for nonlinear
8537 * problems and constraint programs. This gives researchers from different communities an easy access to the
8538 * \SCIP Optimization Suite. See also the \ref AVAILABLEFORMATS "list of readable file formats".
8539 *
8540 * @section C_API C API
8541 *
8542 * The main access point for \SCIP is its API to C. Please refer to the \ref PUBLICAPI documentation
8543 * for further details.
8544 *
8545 * @section CPLUSPLUS C++ wrapper classes
8546 *
8547 * Since \SCIP is written in C, its callable library can be directly accessed from C++. If a user wants to program own
8548 * plugins in C++, there are wrapper classes for all different types of plugins available in the <code>src/objscip</code>
8549 * directory of the \SCIP standard distribution. SCIP provides several examples that were written in C++, see
8550 * \ref EXAMPLES "Examples".
8551 *
8552 * @section SCIPINTERFACES Interfaces for other programming languages
8553 *
8554 * Interfaces for other programming languages are developed and maintained independently from the SCIP Optimization Suite
8555 * on <a href="https://github.com/scipopt">GitHub</a> in order to provide extensions and patches faster
8556 * and to collaborate on them more easily.
8557 *
8558 * - <a href="https://github.com/scipopt/PySCIPOpt">PySCIPOpt</a> provides an extensive open-source interface for Python.
8559 * PySCIPOpt can be installed via <a href="https://anaconda.org/conda-forge/pyscipopt">conda-forge</a>,
8560 * which automatically includes \SCIP.
8561 * PySCIPOpt uses wrappers to allow users to build
8562 * their own plugins without accessing the C code of \SCIP itself.
8563 * Since Python is one of the most commonly used programming languages, especially in the field of
8564 * machine learning, the API gives easy access to the solvers functionality to incorporate \SCIP
8565 * into any python project pipeline, extract data for further analysis and computation as well as allow
8566 * customizing the solving process.
8567 * - <a href="https://github.com/scipopt/SCIP.jl">SCIP.jl</a> is a
8568 * Julia interface that exposes an API identical to the SCIP-C_API and implements the
8569 * MathOptInterface used by most constrained solvers in Julia.
8570 * It can be accessed through the Julia package manager and will install a pre-built version of
8571 * \SCIP if none is provided by the user.
8572 * - There is a <a href="https://github.com/scipopt/MatlabSCIPInterface">Matlab interface</a>
8573 * to use SCIP and SCIP-SDP from Matlab and Octave.
8574 * - <a href="https://github.com/scipopt/JSCIPOpt">JSCIPOpt</a> is an interface for Java.
8575 *
8576 * Contributions to these projects are very welcome.
8577 *
8578 * There are also several third-party python interfaces to the \SCIP Optimization Suite:
8579 * - <a href="https://github.com/eomahony/Numberjack">NUMBERJACK</a> is a constraint programming platform implemented in python.
8580 * It supports a variety of different solvers, one of them being the \SCIP Optimization Suite .
8581 * - <a href="http://code.google.com/p/python-zibopt/">python-zibopt</a> was developed
8582 * by Ryan J. O'Neil and is a python extension of the \SCIP Optimization Suite (not maintained anymore).
8583 * - <a href="http://picos.zib.de/">PICOS</a> is a python interface for conic optimization,
8584 * provided by Guillaume Sagnol.
8585 *
8586 * @section MODELLING Modeling languages
8587 *
8588 * A natural way of formulating an optimization problem is to use a modeling language.
8589 * Besides ZIMPL, which is part of the \SCIP Optimization Suite,
8590 * there are several other modeling tools with a direct interface to \SCIP:
8591 *
8592 * - <a href="https://zimpl.zib.de">ZIMPL</a>, a modeling language for constraint programming,
8593 * - both <a href="http://www.ampl.com/">AMPL</a> and <a href="http://www.gams.com">GAMS</a>,
8594 * are well-suited for modeling mixed-integer linear and nonlinear optimization problems,
8595 * - and <a href="https://projects.coin-or.org/Cmpl">CMPL</a> for mixed-integer linear problems.
8596 * - <a href="https://jump.dev/JuMP.jl/stable/">JuMP</a> accesses SCIP through the Julia interface.
8597 * - <a href="http://users.isy.liu.se/johanl/yalmip/pmwiki.php?n=Main.HomePage">YALMIP</a> by Johan L&ouml;fberg provides a
8598 * free modeling language.
8599 *
8600 * The AMPL and ZIMPL interfaces are included in the \SCIP distribution,
8601 * the GAMS interface is available <a href="https://github.com/coin-or/GAMSlinks">here</a>.
8602 *
8603 */
8604
8605 /**@defgroup PUBLICAPI Public API of SCIP
8606 * @brief methods and headers of the public C-API of \SCIP. Please refer to \ref DOC "" for information how to use the reference manual.
8607 *
8608 * \PUBLICAPIDESCRIPTION
8609 *
8610 *
8611 */
8612
8613/**@defgroup PUBLICCOREAPI Core API
8614 * @ingroup PUBLICAPI
8615 * @brief methods and headers of the plugin-independent C-API provided by the \SCIP header file scip.h.
8616 *
8617 * This module comprises methods provided by the header file scip.h. Including this header into a user-written extension
8618 * suffices to have all plugin-independent functionality of \SCIP available. Plugin-independent
8619 * user functionality includes the
8620 *
8621 * - creation of problems that \SCIP should solve
8622 * - fine-grained access to initiate the solving process of \SCIP
8623 * - access to all sorts of solving process statistics
8624 * - commonly used data structures and algorithms
8625 * - the management of plugins
8626 * - ...
8627 *
8628 * In order facilitate the navigation through the core API of \SCIP, it is structured into different modules.
8629 */
8630
8631/**@defgroup TYPEDEFINITIONS Type Definitions
8632 * @ingroup PUBLICCOREAPI
8633 * @brief type definitions and callback declarations
8634 *
8635 * This page lists headers which contain type definitions of callback methods.
8636 *
8637 * All headers below include the descriptions of callback methods of
8638 * certain plugins. For more detail see the corresponding header.
8639 */
8640
8641/**@defgroup PublicProblemMethods Problem Creation
8642 * @ingroup PUBLICCOREAPI
8643 * @brief methods to create a problem that \SCIP should solve
8644 *
8645 * This module summarizes the main methods needed to create a problem for \SCIP, and access its most important members:
8646 * - Declaring, adding, accessing, and changing variables of the problem
8647 * - Declaring, adding, accessing, and changing constraints of the problem
8648 * - Creating, adding, accessing, changing, and checking of solutions to the problem
8649 *
8650 * @note These core methods are not sufficient to create constraints of a certain type that is provided by the default plugins of \SCIP.
8651 * An example would be the creation of a linear constraint for which the methods provided by the
8652 * \ref cons_linear.h "linear constraint handler" must be used. Such methods are provided by the default plugins of \SCIP
8653 * and can be found in the \ref PUBLICPLUGINAPI.
8654 */
8655
8656/**@defgroup GeneralSCIPMethods SCIP
8657 * @ingroup PublicProblemMethods
8658 * @brief methods to manipulate a SCIP object
8659 */
8660
8661/**@defgroup GlobalProblemMethods Global Problem
8662 * @ingroup PublicProblemMethods
8663 * @brief methods to create, read and modify a global problem together with its callbacks
8664 */
8665
8666/**@defgroup PublicVariableMethods Problem Variables
8667 * @ingroup PublicProblemMethods
8668 * @brief public methods for problem variables
8669 */
8670
8671/**@defgroup PublicConstraintMethods Problem Constraints
8672 * @ingroup PublicProblemMethods
8673 * @brief Public methods for constraints
8674 */
8675
8676/**@defgroup PublicSolutionMethods Primal Solution
8677 * @ingroup PublicProblemMethods
8678 * @brief methods to create and change primal solutions of \SCIP
8679 */
8680
8681/**@defgroup CopyMethods Problem Copies
8682 * @ingroup PublicProblemMethods
8683 * @brief methods to copy problems between a source and a target \SCIP
8684 */
8685
8686
8687 /**@defgroup PublicSolveMethods Solving Process
8688 * @ingroup PUBLICCOREAPI
8689 * @brief methods to control the solving process of \SCIP
8690 *
8691 * This large group of methods and modules comprises the solving process related API of \SCIP. This includes
8692 *
8693 * -# changing parameters to control the solver behavior
8694 * -# access search tree related information
8695 * -# access relaxation information
8696 * -# access various solving process statistics
8697 * -# solve auxiliary relaxations and subproblems using LP/NLP diving or probing mode
8698 */
8699
8700/**@defgroup PublicSolvingStatsMethods Solving Statistics
8701 * @ingroup PublicSolveMethods
8702 * @brief methods to query statistics about the solving process
8703 */
8704
8705/**@defgroup ParameterMethods Parameter
8706 * @ingroup PublicSolveMethods
8707 * @brief methods to create, query, and print user parameters
8708 */
8709
8710/**@defgroup PublicEventMethods Event Handling
8711 * @ingroup PublicSolveMethods
8712 * @brief methods to create, catch, process, and drop events during the solving process of \SCIP
8713 *
8714 * Events can only be caught during the operation on the transformed problem.
8715 * Events on variables can only be caught for transformed variables.
8716 * If you want to catch an event for an original variable, you have to get the corresponding transformed variable
8717 * with a call to SCIPgetTransformedVar() and catch the event on the transformed variable.
8718 */
8719
8720/**@defgroup PublicLPMethods LP Relaxation
8721 * @ingroup PublicSolveMethods
8722 * @brief methods to build and access LP relaxation information
8723 * @see methods to interact with \ref PublicColumnMethods "LP columns" and \ref PublicRowMethods "LP rows"
8724 */
8725
8726/**@defgroup PublicColumnMethods LP Column
8727 * @ingroup PublicLPMethods
8728 * @brief public methods for LP columns
8729 */
8730
8731/**@defgroup PublicRowMethods LP Row
8732 * @ingroup PublicLPMethods
8733 * @brief public methods for LP rows
8734 */
8735
8736/**@defgroup PublicCutMethods Cuts and Cutpools
8737 * @ingroup PublicLPMethods
8738 * @brief common methods used to manipulate, generate, and strengthen cuts and to organize the cutpool
8739 */
8740
8741/**@defgroup PublicLPDivingMethods LP Diving
8742 * @ingroup PublicLPMethods
8743 * @brief methods to initiate and conduct LP diving
8744 */
8745
8746/**@defgroup PublicNLPMethods NLP Relaxation
8747 * @ingroup PublicSolveMethods
8748 * @brief methods for the nonlinear relaxation
8749 */
8750
8751/**@defgroup PublicNLRowMethods Nonlinear Rows
8752 * @ingroup PublicNLPMethods
8753 * @brief methods for the creation and interaction with rows of the NLP relaxation
8754 */
8755
8756/**@defgroup PublicNLPDiveMethods NLP Diving
8757 * @ingroup PublicNLPMethods
8758 * @brief methods to initiate and conduct NLP Diving
8759 */
8760
8761/**@defgroup PublicConflictMethods Conflict Analysis
8762 * @ingroup PublicSolveMethods
8763 * @brief public methods for conflict analysis
8764 */
8765
8766/**@defgroup PublicBranchingMethods Branching
8767 * @ingroup PublicSolveMethods
8768 * @brief methods for branching on LP solutions, relaxation solutions, and pseudo solutions
8769 *
8770 * @see \ref PublicVariableMethods "Public Variable methods" contains some typical variable branching score functions
8771 */
8772
8773/**@defgroup LocalSubproblemMethods Local Subproblem
8774 * @ingroup PublicSolveMethods
8775 * @brief methods to query information about or strengthen the problem at the current local search node
8776 */
8777
8778/**@defgroup PublicTreeMethods Search Tree
8779 * @ingroup PublicSolveMethods
8780 * @brief methods to query search tree related information
8781 * @see \ref PublicNodeMethods "Public methods for nodes"
8782 */
8783
8784/**@defgroup PublicNodeMethods Nodes
8785 * @ingroup PublicTreeMethods
8786 * @brief methods for nodes of the search tree of \SCIP
8787 */
8788
8789/**@defgroup PublicProbingMethods Probing
8790 * @ingroup PublicSolveMethods
8791 * @brief methods to initiate and control the probing mode of \SCIP
8792 */
8793
8794/**@defgroup PublicReoptimizationMethods Reoptimization
8795 * @ingroup PublicSolveMethods
8796 * @brief methods for reoptimization related tasks
8797 */
8798
8799/** @defgroup DataStructures Data Structures
8800 * @ingroup PUBLICCOREAPI
8801 * @brief commonly used data structures
8802 *
8803 * Below you find a list of available data structures
8804 */
8805
8806/** @defgroup DisjointSet Disjoint Set (Union Find)
8807 * @ingroup DataStructures
8808 * @brief weighted disjoint set (union find) data structure with path compression
8809 *
8810 * Weighted Disjoint Set is a data structure to quickly update and query connectedness information
8811 * between nodes of a graph. Disjoint Set is also known as Union Find.
8812 */
8813
8814/**@defgroup PublicDynamicArrayMethods Dynamic Arrays
8815 * @ingroup DataStructures
8816 * @brief methods for the creation and access of dynamic arrays
8817 */
8818
8819/**@defgroup DirectedGraph Directed Graph
8820 * @ingroup DataStructures
8821 * @brief graph structure with common algorithms for directed and undirected graphs
8822 */
8823
8824/**@defgroup DecompMethods Decomposition data structure
8825 * @ingroup DataStructures
8826 * @brief methods for creating and accessing user decompositions
8827 */
8828
8829/**@defgroup MiscellaneousMethods Miscellaneous Methods
8830 * @ingroup PUBLICCOREAPI
8831 * @brief commonly used methods from different categories
8832 *
8833 * Below you find a list of miscellaneous methods grouped by different categories
8834 */
8835
8836/**@defgroup PublicValidationMethods Validation
8837 * @ingroup PUBLICCOREAPI
8838 * @brief methods for validating the correctness of a solving process
8839 */
8840
8841/**@defgroup PublicMemoryMethods Memory Management
8842 * @ingroup MiscellaneousMethods
8843 * @brief methods and macros to use the \SCIP memory management
8844 *
8845 * @see \ref MEMORY "Using the memory functions of SCIP" for more information
8846 */
8847
8848/**@defgroup PublicTimingMethods Timing
8849 * @ingroup MiscellaneousMethods
8850 * @brief methods for timing
8851 */
8852
8853/**@defgroup PublicBanditMethods Bandit Algorithms
8854 * @ingroup MiscellaneousMethods
8855 * @brief methods for bandit algorithms
8856 */
8857
8858
8859
8860/**@defgroup DebugSolutionMethods Debug Solution
8861 * @ingroup PUBLICCOREAPI
8862 * @brief methods to control the SCIP debug solution mechanism, see also \ref DEBUG
8863 */
8864
8865/**@defgroup MessageOutputMethods Messaging
8866 * @ingroup PUBLICCOREAPI
8867 * @brief message output methods
8868 */
8869
8870/**@defgroup PluginManagementMethods Methods for managing plugins
8871 * @ingroup PUBLICCOREAPI
8872 * @brief Methods for the inclusion and management of SCIP plugins and callback functions
8873 *
8874 */
8875
8876/**@defgroup PublicBendersMethods Benders' decomposition
8877 * @ingroup PluginManagementMethods
8878 * @brief methods for Benders' decomposition plugins
8879 */
8880
8881/**@defgroup PublicBenderscutsMethods Benders' decomposition cuts
8882 * @ingroup PluginManagementMethods
8883 * @brief methods for Benders' decomposition cuts plugins
8884 */
8885
8886/**@defgroup PublicBranchRuleMethods Branching Rules
8887 * @ingroup PluginManagementMethods
8888 * @brief methods for branching rule plugins
8889 */
8890
8891/**@defgroup PublicCompressionMethods Tree Compression
8892 * @ingroup PluginManagementMethods
8893 * @brief public methods for tree compressions
8894 */
8895
8896/**@defgroup PublicConflicthdlrMethods Conflict Analysis
8897 * @ingroup PluginManagementMethods
8898 * @brief public methods for conflict handlers
8899 */
8900
8901/**@defgroup PublicConshdlrMethods Constraint handlers
8902 * @ingroup PluginManagementMethods
8903 * @brief methods for constraint handlers
8904 */
8905
8906/**@defgroup PublicCutSelectorMethods Cut Selector
8907 * @ingroup PluginManagementMethods
8908 * @brief methods for cut selectors
8909 */
8910
8911/**@defgroup PublicDialogMethods Dialogs
8912 * @ingroup PluginManagementMethods
8913 * @brief public methods for user interface dialogs
8914 */
8915
8916/**@defgroup PublicDisplayMethods Displays
8917 * @ingroup PluginManagementMethods
8918 * @brief methods for the inclusion and access of display plugins
8919 */
8920
8921/**@defgroup PublicEventHandlerMethods Event Handler
8922 * @ingroup PluginManagementMethods
8923 * @brief methods for event handlers
8924 */
8925
8926/**@defgroup PublicExprHandlerMethods Expression Handler
8927 * @ingroup PluginManagementMethods
8928 * @brief methods for expression handlers
8929 */
8930
8931/**@defgroup PublicHeuristicMethods Primal Heuristics
8932 * @ingroup PluginManagementMethods
8933 * @brief methods for primal heuristic plugins
8934 */
8935
8936/**@defgroup PublicDivesetMethods Dive sets
8937 * @ingroup PublicSpecialHeuristicMethods
8938 * @brief methods for dive sets to control the generic diving algorithm
8939 */
8940
8941/**@defgroup PublicNodeSelectorMethods Node Selector
8942 * @ingroup PluginManagementMethods
8943 * @brief methods for node selector plugin management
8944 */
8945
8946/**@defgroup PublicNlhdlrInterfaceMethods Nonlinear Handlers
8947 * @ingroup PluginManagementMethods
8948 * @brief methods for the management of nonlinear handlers
8949 */
8950
8951/**@defgroup PublicPresolverMethods Presolver
8952 * @ingroup PluginManagementMethods
8953 * @brief methods for presolver plugins
8954 */
8955
8956/**@defgroup PublicPricerMethods Pricer
8957 * @ingroup PluginManagementMethods
8958 * @brief methods to include and access pricer plugins of \SCIP
8959 */
8960
8961/**@defgroup PublicPropagatorMethods Propagators
8962 * @ingroup PluginManagementMethods
8963 * @brief methods for propagator plugins
8964 */
8965
8966/**@defgroup PublicReaderMethods Reader
8967 * @ingroup PluginManagementMethods
8968 * @brief methods for the inclusion and access to reader plugins of \SCIP
8969 */
8970
8971/**@defgroup PublicRelaxatorMethods Relaxation Handlers
8972 * @ingroup PluginManagementMethods
8973 * @brief public methods for relaxation handlers
8974 */
8975
8976/**@defgroup PublicSeparatorMethods Separators
8977 * @ingroup PluginManagementMethods
8978 * @brief methods for separator plugins
8979 */
8980
8981/**@defgroup PublicTableMethods Tables
8982 * @ingroup PluginManagementMethods
8983 * @brief methods for the inclusion and access of statistics tables
8984 */
8985
8986/**@defgroup PublicConcsolverTypeMethods Concurrent Solver Types
8987 * @ingroup PluginManagementMethods
8988 * @brief methods for concurrent solver type plugins
8989 */
8990
8991/**@defgroup PublicNLPIInterfaceMethods NLP solver interfaces
8992 * @ingroup PluginManagementMethods
8993 * @brief methods for the management of NLP solver interfaces
8994 */
8995
8996/**@defgroup PublicExternalCodeMethods External Codes
8997 * @ingroup PluginManagementMethods
8998 * @brief methods to access information about external codes used by \SCIP
8999 */
9000
9001/**@defgroup PublicParallelMethods Parallel Interface
9002 * @ingroup PUBLICCOREAPI
9003 * @brief methods to construct the parallel interface of \SCIP
9004 */
9005
9006 /**@defgroup PUBLICPLUGINAPI Plugin API of SCIP
9007 * @ingroup PUBLICAPI
9008 * @brief core API extensions provided by the default plugins of \SCIP, includable via scipdefplugins.h.
9009 *
9010 * All default plugins of \SCIP, especially the default \ref CONSHDLRS "constraint handlers", provide
9011 * valuable extensions to the \ref PUBLICCOREAPI "core API" of \SCIP. These methods are made available
9012 * by including scipdefplugins.h to user-written extensions.
9013 *
9014 * For a better overview, this page lists all default plugin headers structured into modules based on their individual
9015 * topic.
9016 *
9017 * All of the modules listed below provide functions that are allowed to be used by user-written extensions of \SCIP.
9018 */
9019 /**@defgroup INTERNALAPI Internal API of SCIP
9020 * @brief internal API methods that should only be used by the core of \SCIP
9021 *
9022 * This page lists the header files of internal API methods. In contrast to the public API, these internal methods
9023 * should not be used by user plugins and extensions of SCIP. Please consult
9024 * \ref PUBLICCOREAPI "the Core API" and \ref PUBLICPLUGINAPI "Plugin API" for the complete API available to user plugins.
9025 *
9026 */
9027
9028/**@defgroup BENDERS Benders' decomposition implementations
9029 * @ingroup PUBLICPLUGINAPI
9030 * @brief methods and files provided by the default Benders' decomposition implementations of \SCIP
9031 *
9032 * A detailed description what a Benders' decomposition implementation does and how to add a Benders' decomposition
9033 * implementations to SCIP can be found
9034 * \ref BENDER "here".
9035 */
9036
9037/**@defgroup BendersIncludes Inclusion methods
9038 * @ingroup BENDERS
9039 * @brief methods to include specific Benders' decomposition implementations into \SCIP
9040 *
9041 * This module contains methods to include specific Benders' decomposition implementations into \SCIP.
9042 *
9043 * @note All default plugins can be included at once (including all Benders' decomposition implementations) using
9044 * SCIPincludeDefaultPlugins()
9045 *
9046 */
9047
9048/**@defgroup BENDERSCUTS Benders' decomposition cut method
9049 * @ingroup PUBLICPLUGINAPI
9050 * @brief methods and files provided by the default Benders' decomposition cut method of \SCIP
9051 *
9052 * A detailed description what a Benders' decomposition cut method does and how to add a Benders' decomposition
9053 * cut method to SCIP can be found
9054 * \ref BENDERSCUT "here".
9055 */
9056
9057/**@defgroup BenderscutIncludes Inclusion methods
9058 * @ingroup BENDERSCUTS
9059 * @brief methods to include specific Benders' decomposition cut methods into \SCIP
9060 *
9061 * This module contains methods to include specific Benders' decomposition cut methods into \SCIP.
9062 *
9063 * @note The Benders' decomposition cut methods are linked to each Benders' decomposition implementation. Thus, the
9064 * default Benders' decomposition implementations automatically include the necessary Benders' decomposition cut
9065 * methods. For custom Benders' decomposition implementations, you can call SCIPincludeDefaultBendersCuts() in the
9066 * SCIPincludeBendersMybenders() include function.
9067 *
9068 */
9069
9070/**@defgroup BRANCHINGRULES Branching Rules
9071 * @ingroup PUBLICPLUGINAPI
9072 * @brief methods and files provided by the default branching rules of \SCIP
9073 *
9074 * A detailed description what a branching rule does and how to add a branching rule to SCIP can be found
9075 * \ref BRANCH "here".
9076 */
9077
9078/**@defgroup BranchingRuleIncludes Inclusion methods
9079 * @ingroup BRANCHINGRULES
9080 * @brief methods to include specific branching rules into \SCIP
9081 *
9082 * This module contains methods to include specific branching rules into \SCIP.
9083 *
9084 * @note All default plugins can be included at once (including all branching rules) using SCIPincludeDefaultPlugins()
9085 *
9086 */
9087
9088/**@defgroup CONSHDLRS Constraint Handlers
9089 * @ingroup PUBLICPLUGINAPI
9090 * @brief methods and files provided by the default constraint handlers of \SCIP
9091 *
9092 * A detailed description what a constraint handler does and how to add a constraint handler to SCIP can be found
9093 * \ref CONS "here".
9094 */
9095
9096/**@defgroup ConshdlrIncludes Inclusion methods
9097 * @ingroup CONSHDLRS
9098 * @brief methods to include specific constraint handlers into \SCIP
9099 *
9100 * This module contains methods to include specific constraint handlers into \SCIP.
9101 *
9102 * @note All default plugins can be included at once (including all default constraint handlers) using SCIPincludeDefaultPlugins()
9103 *
9104 */
9105
9106/**@defgroup CUTSELECTORS Cut Selectors
9107 * @ingroup PUBLICPLUGINAPI
9108 * @brief methods and files provided by the default cut selectors of \SCIP
9109 *
9110 * A detailed description what a cut selector does and how to add a cut selector to SCIP can be found
9111 * \ref CUTSEL "here".
9112 */
9113
9114/**@defgroup CutSelectorIncludes Inclusion methods
9115 * @ingroup CUTSELECTORS
9116 * @brief methods to include specific cut selectors into \SCIP
9117 *
9118 * This module contains methods to include specific cut selectors into \SCIP.
9119 *
9120 * @note All default plugins can be included at once (including all default cut selectors) using SCIPincludeDefaultPlugins()
9121 *
9122 */
9123
9124/**@defgroup DIALOGS Dialogs
9125 * @ingroup PUBLICPLUGINAPI
9126 * @brief methods and files provided by the default dialogs of \SCIP
9127 *
9128 * A detailed description what a dialog does and how to add a dialog to SCIP can be found
9129 * \ref DIALOG "here".
9130 */
9131
9132/**@defgroup DialogIncludes Inclusion methods
9133 * @ingroup DIALOGS
9134 * @brief methods to include specific dialogs into \SCIP
9135 *
9136 * This module contains methods to include specific dialogs into \SCIP.
9137 *
9138 * @note All default plugins can be included at once (including all default dialogs) using SCIPincludeDefaultPlugins()
9139 *
9140 */
9141
9142/**@defgroup DISPLAYS Displays
9143 * @ingroup PUBLICPLUGINAPI
9144 * @brief methods and files provided by the default displays (output columns) of \SCIP
9145 *
9146 * A detailed description what a display does and how to add a display to SCIP can be found
9147 * \ref DISP "here".
9148 *
9149 */
9150
9151/**@defgroup DisplayIncludes Inclusion methods
9152 * @ingroup DISPLAYS
9153 * @brief methods to include specific displays into \SCIP
9154 *
9155 * This module contains methods to include specific displays into \SCIP.
9156 *
9157 * @note All default plugins can be included at once (including all default displays) using SCIPincludeDefaultPlugins()
9158 *
9159 */
9160
9161/**@defgroup EXPRHDLRS Expression Handlers
9162 * @ingroup PUBLICPLUGINAPI
9163 * @brief methods and files provided by the default expressions handlers of \SCIP
9164 */
9165
9166/**@defgroup ExprhdlrIncludes Inclusion methods
9167 * @ingroup EXPRHDLRS
9168 * @brief methods to include specific expression handlers into \SCIP
9169 *
9170 * This module contains methods to include specific expression handlers into \SCIP.
9171 *
9172 * @note All default plugins can be included at once (including all default expression handlers) using SCIPincludeDefaultPlugins()
9173 *
9174 */
9175
9176/**@defgroup EXPRINTS Expression Interpreter
9177 * @ingroup PUBLICPLUGINAPI
9178 * @brief methods and files provided by the default expression interpreters of \SCIP
9179 *
9180 * A detailed description what a expression interpreter does and how to add a expression interpreter to SCIP can be found
9181 * \ref EXPRINT "here".
9182 */
9183
9184/**@defgroup FILEREADERS File Readers
9185 * @ingroup PUBLICPLUGINAPI
9186 * @brief This page contains a list of all file readers which are currently available.
9187 *
9188 * @section AVAILABLEFORMATS List of readable file formats
9189 *
9190 * The \ref SHELL "interactive shell" and the callable library are capable of reading/parsing several different file
9191 * formats.
9192 *
9193 * <table>
9194 * <tr><td>\ref reader_bnd.h "BND format"</td> <td>for variable bounds</td></tr>
9195 * <tr><td>\ref reader_cip.h "CIP format"</td> <td>for SCIP's constraint integer programming format</td></tr>
9196 * <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>
9197 * <tr><td>\ref reader_diff.h "DIFF format"</td> <td>for reading a new objective function for mixed-integer programs</td></tr>
9198 * <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>
9199 * <tr><td>\ref reader_lp.h "LP format"</td> <td>for mixed-integer (quadratically constrained quadratic) programs (CPLEX)</td></tr>
9200 * <tr><td>\ref reader_mps.h "MPS format"</td> <td>for mixed-integer (quadratically constrained quadratic) programs</td></tr>
9201 * <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
9202 * <tr><td>\ref reader_opb.h "OPB format"</td> <td>for pseudo-Boolean optimization instances</td></tr>
9203 * <tr><td>\ref reader_osil.h "OSiL format"</td> <td>for mixed-integer nonlinear programs</td></tr>
9204 * <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>
9205 * <tr><td>\ref reader_sol.h "SOL format"</td> <td>for solutions; XML-format (read-only) or raw SCIP format</td></tr>
9206 * <tr><td>\ref reader_wbo.h "WBO format"</td> <td>for weighted pseudo-Boolean optimization instances</td></tr>
9207 * <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
9208 * programming problems [read only]</td></tr>
9209 * </table>
9210 *
9211 * @section ADDREADER How to add a file reader
9212 *
9213 * A detailed description what a file reader does and how to add a file reader to SCIP can be found
9214 * \ref READER "here".
9215 *
9216 */
9217
9218/**@defgroup FileReaderIncludes Inclusion methods
9219 * @ingroup FILEREADERS
9220 * @brief methods to include specific file readers into \SCIP
9221 *
9222 * This module contains methods to include specific file readers into \SCIP.
9223 *
9224 * @note All default plugins can be included at once (including all default file readers) using SCIPincludeDefaultPlugins()
9225 *
9226 */
9227
9228/**@defgroup PARALLEL Parallel interface methods
9229 * @ingroup INTERNALAPI
9230 * @brief headers and methods for the parallel interface of \SCIP
9231 *
9232 */
9233
9234/**@defgroup PublicSymmetryMethods Symmetry
9235 * @ingroup INTERNALAPI
9236 * @brief methods for symmetry handling
9237 */
9238
9239/**@defgroup FileReaderIncludes Inclusion methods
9240 * @ingroup FILEREADERS
9241 * @brief methods to include specific file readers into \SCIP
9242 *
9243 * This module contains methods to include specific file readers into \SCIP.
9244 *
9245 * @note All default plugins can be included at once (including all default file readers) using SCIPincludeDefaultPlugins()
9246 *
9247 */
9248
9249/**@defgroup LPIS LP Solver Interface
9250 * @ingroup PUBLICPLUGINLPI
9251 * @brief methods and files provided by the LP solver interface of \SCIP
9252 *
9253 * \SCIP uses external tools to solve LP relaxations. The communication
9254 * is realized through an LP interface.
9255 *
9256 * This page lists public interface methods that every LP interface provides.
9257 * Find the concrete implementation for your LP solver
9258 * under "src/lpi/".
9259 *
9260 * @see \ref LPI for a list of available LP solver interfaces
9261 */
9262
9263/**@defgroup NODESELECTORS Node Selectors
9264 * @ingroup PUBLICPLUGINAPI
9265 * @brief methods and files provided by the default node selectors of \SCIP
9266 *
9267 * A detailed description what a node selector does and how to add a node selector to SCIP can be found
9268 * \ref NODESEL "here".
9269 */
9270
9271/**@defgroup NodeSelectorIncludes Inclusion methods
9272 * @ingroup NODESELECTORS
9273 * @brief methods to include specific node selectors into \SCIP
9274 *
9275 * This module contains methods to include specific node selectors into \SCIP.
9276 *
9277 * @note All default plugins can be included at once (including all default node selectors) using SCIPincludeDefaultPlugins()
9278 *
9279 */
9280
9281/**@defgroup NLHDLRS Nonlinear Handlers
9282 * @ingroup PUBLICPLUGINAPI
9283 * @brief methods and files provided by the default nonlinear handlers of \SCIP
9284 */
9285
9286/**@defgroup NlhdlrIncludes Inclusion methods
9287 * @ingroup NLHDLRS
9288 * @brief methods to include specific nonlinear handlers into \SCIP
9289 *
9290 * This module contains methods to include specific nonlinear handlers into \SCIP.
9291 *
9292 * @note All default plugins can be included at once (including all default nonlinear handlers) using SCIPincludeDefaultPlugins()
9293 *
9294 */
9295
9296/**@defgroup NLPIS NLP Solver Interfaces
9297 * @ingroup PUBLICPLUGINAPI
9298 * @brief methods and files provided by the default NLP solver interfaces of \SCIP
9299 *
9300 * A detailed description what a NLP solver interface does and how to add a NLP solver interface to SCIP can be found
9301 * \ref NLPI "here".
9302 */
9303
9304/**@defgroup NLPIIncludes Inclusion methods
9305 * @ingroup NLPIS
9306 * @brief methods to include specific NLP solver interfaces into \SCIP
9307 *
9308 * This module contains methods to include specific NLP solver interfaces into \SCIP.
9309 *
9310 * @note All default plugins can be included at once (including all default NLP solver interfaces) using SCIPincludeDefaultPlugins()
9311 *
9312 */
9313
9314/**@defgroup PRESOLVERS Presolvers
9315 * @ingroup PUBLICPLUGINAPI
9316 * @brief methods and files provided by the default presolvers of \SCIP
9317 *
9318 * A detailed description what a presolver does and how to add a presolver to SCIP can be found
9319 * \ref PRESOL "here".
9320 */
9321
9322/**@defgroup PresolverIncludes Inclusion methods
9323 * @ingroup PRESOLVERS
9324 * @brief methods to include specific presolvers into \SCIP
9325 *
9326 * This module contains methods to include specific presolvers into \SCIP.
9327 *
9328 * @note All default plugins can be included at once (including all default presolvers) using SCIPincludeDefaultPlugins()
9329 *
9330 */
9331
9332/**@defgroup PRICERS Pricers
9333 * @ingroup PUBLICPLUGINAPI
9334 * @brief methods and files provided by the default pricers of \SCIP
9335 *
9336 * Per default there exist no variable pricer. A detailed description what a variable pricer does and how to add a
9337 * variable pricer to SCIP can be found \ref PRICER "here".
9338 */
9339
9340/**@defgroup PricerIncludes Inclusion methods
9341* @ingroup PRICERS
9342* @brief methods to include specific pricers into \SCIP
9343*
9344* This module contains methods to include specific pricers into \SCIP.
9345*
9346* @note All default plugins can be included at once using SCIPincludeDefaultPlugins(). There exists no pricer per default.
9347* In order to see examples of variable pricers, please consult the \ref EXAMPLES "Coding Examples" of \SCIP.
9348*
9349*/
9350
9351/**@defgroup PRIMALHEURISTICS Primal Heuristics
9352 * @ingroup PUBLICPLUGINAPI
9353 * @brief methods and files provided by the default primal heuristics of \SCIP
9354 *
9355 * A detailed description what a primal heuristic does and how to add a primal heuristic to SCIP can be found
9356 * \ref HEUR "here".
9357 */
9358
9359/**@defgroup PrimalHeuristicIncludes Inclusion methods
9360 * @ingroup PRIMALHEURISTICS
9361 * @brief methods to include specific primal heuristics into \SCIP
9362 *
9363 * This module contains methods to include specific primal heuristics into \SCIP.
9364 *
9365 * @note All default plugins can be included at once (including all default primal heuristics) using SCIPincludeDefaultPlugins()
9366 *
9367 */
9368
9369/**@defgroup PROPAGATORS Propagators
9370 * @ingroup PUBLICPLUGINAPI
9371 * @brief methods and files provided by the default propagators of \SCIP
9372 *
9373 * A detailed description what a propagator does and how to add a propagator to SCIP can be found
9374 * \ref PROP "here".
9375 */
9376
9377/**@defgroup PropagatorIncludes Inclusion methods
9378 * @ingroup PROPAGATORS
9379 * @brief methods to include specific propagators into \SCIP
9380 *
9381 * This module contains methods to include specific propagators into \SCIP.
9382 *
9383 * @note All default plugins can be included at once (including all default propagators) using SCIPincludeDefaultPlugins()
9384 *
9385 */
9386
9387/**@defgroup RELAXATORS Relaxation Handlers
9388 * @ingroup PUBLICPLUGINAPI
9389 * @brief methods and files provided by the default relaxation handlers of \SCIP
9390 *
9391 * A detailed description what a relaxation handler does and how to add a relaxation handler to SCIP can be found
9392 * \ref RELAX "here". Note that the linear programming relaxation is not implemented via the relaxation handler plugin.
9393 * Per default no relaxation handler exists in SCIP. However, there are two relaxation handlers in the
9394 * \ref RELAXATOR_MAIN "Relaxator example".
9395 */
9396
9397/**@defgroup SEPARATORS Separators
9398 * @ingroup PUBLICPLUGINAPI
9399 * @brief methods and files provided by the default separators of \SCIP
9400 *
9401 * A detailed description what a separator does and how to add a separator to SCIP can be found
9402 * \ref SEPA "here".
9403 */
9404
9405/**@defgroup SeparatorIncludes Inclusion methods
9406 * @ingroup SEPARATORS
9407 * @brief methods to include specific separators into \SCIP
9408 *
9409 * This module contains methods to include specific separators into \SCIP.
9410 *
9411 * @note All default plugins can be included at once (including all default separators) using SCIPincludeDefaultPlugins()
9412 *
9413 */
9414
9415/**@defgroup TABLES Tables
9416 * @ingroup PUBLICPLUGINAPI
9417 * @brief methods and files provided by the default statistics tables of \SCIP
9418 *
9419 * A detailed description what a table does and how to add a table to SCIP can be found
9420 * \ref TABLE "here".
9421 *
9422 */
9423
9424/**@defgroup TableIncludes Inclusion methods
9425 * @ingroup TABLES
9426 * @brief methods to include specific tables into \SCIP
9427 *
9428 * This module contains methods to include specific statistics tables into \SCIP.
9429 *
9430 * @note All default plugins can be included at once (including all default statisticstables) using SCIPincludeDefaultPlugins()
9431 *
9432 */
9433
9434/**@defgroup PublicToleranceMethods Computations With Tolerances
9435 * @ingroup NumericalMethods
9436 * @brief methods used by the majority of operations involving floating-point computations in \SCIP
9437 *
9438 * - query the numerical tolerances of \SCIP, as well as special values such as infinity.
9439 * - change tolerances inside relaxations
9440 * - epsilon-comparison methods for floating point numbers
9441 */
9442
9443/** @defgroup CFILES Implementation files (.c files)
9444 * @brief implementation files (.c files) of the SCIP core and the default plugins
9445 *
9446 * The core provides the functionality for creating problems, variables, and general constraints.
9447 * The default plugins of SCIP provide a mix of public API function and private, static function and callback declarations.
9448 */
9449
9450/** @defgroup DEFPLUGINS SCIP Default Plugins
9451 * @ingroup CFILES
9452 * @brief implementation files (.c files) of the SCIP default plugins
9453 *
9454 * The SCIP default plugins provide a mix of public API function and private, static function and callback declarations.
9455 */
9456
9457/** @defgroup OTHER_CFILES Other implementation files of SCIP
9458 * @ingroup CFILES
9459 * @brief other implementation files of SCIP
9460 *
9461 * Relevant core and other functionality of SCIP.
9462 */