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-2025 Zuse Institute Berlin (ZIB) */
7/* */
8/* Licensed under the Apache License, Version 2.0 (the "License"); */
9/* you may not use this file except in compliance with the License. */
10/* You may obtain a copy of the License at */
11/* */
12/* http://www.apache.org/licenses/LICENSE-2.0 */
13/* */
14/* Unless required by applicable law or agreed to in writing, software */
15/* distributed under the License is distributed on an "AS IS" BASIS, */
16/* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. */
17/* See the License for the specific language governing permissions and */
18/* limitations under the License. */
19/* */
20/* You should have received a copy of the Apache-2.0 license */
21/* along with SCIP; see the file LICENSE. If not visit scipopt.org. */
22/* */
23/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
24
25/**@file xternal.c
26 * @brief main document page
27 * @author Tobias Achterberg
28 * @author Timo Berthold
29 * @author Tristan Gally
30 * @author Gerald Gamrath
31 * @author Stefan Heinz
32 * @author Gregor Hendel
33 * @author Mathias Kinder
34 * @author Marc Pfetsch
35 * @author Stefan Vigerske
36 * @author Robert Waniek
37 * @author Kati Wolter
38 * @author Michael Winkler
39 */
40
41/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
42
43/** @mainpage Overview
44 *
45 * @section WHATISSCIP What is SCIP?
46 *
47 * \SCIP is a framework to solve constraint integer programs (CIPs) and mixed-integer nonlinear programs. In particular,
48 *
49 * - \SCIP incorporates a mixed-integer programming (MIP) solver as well as
50 * - an LP based mixed-integer nonlinear programming (MINLP) solver, and
51 * - is a framework for branch-and-cut-and-price.
52 *
53 * See the web site of <a href="http://scipopt.org">\SCIP</a> for more information about licensing and to download \SCIP.
54 *
55 * <b style="color: blue">If you are new to SCIP and don't know where to start you should have a look at the
56 * @ref GETTINGSTARTED "first steps walkthrough"
57 * .</b>
58 *
59 * @section TABLEOFCONTENTS Structure of this manual
60 *
61 * This manual gives an accessible introduction to the functionality of the SCIP code in the following chapters
62 *
63 * Setup and news
64 * - @subpage INSTALL
65 * - @subpage FAQ
66 * - @subpage CHG
67 *
68 * Tutorials and guides
69 * - @subpage GETTINGSTARTED
70 * - @subpage SHELL
71 * - @subpage PROGRAMMING "Important programming concepts for working with(in) SCIP"
72 * - @subpage START
73 * - @subpage DOC
74 * - @subpage HOWTOADD "Detailed guides for adding user plugins"
75 * - @subpage HOWTOUSESECTION "Detailed guides for advanced SCIP topics"
76 *
77 * Examples and applications
78 * - @subpage EXAMPLES "Coding examples in C and C++ in the source code distribution"
79 * - @subpage APPLICATIONS "Extensions of SCIP for specific applications"
80 *
81 * References
82 * - @subpage WHATPROBLEMS "Supported types of optimization problems"
83 * - @subpage FILEREADERS "Readable file formats"
84 * - @subpage INTERFACES
85 * - @subpage PARAMETERS
86 * - @subpage AUTHORS "SCIP Authors"
87 * - @subpage LICENSE
88 * - @subpage EXTERNALDOC "Links to external documentation"
89 *
90 *
91 * @section QUICKSTART Quickstart
92 *
93 * Let's consider the following minimal example in LP format. A 4-variable problem with a single, general integer
94 * variable and three linear constraints
95 *
96 * \verbinclude simple.lp
97 *
98 * Saving this file as "simple.lp" allows to read it into SCIP and solve it by calling the scip binary with the `-f` flag to solve the problem from the provided file and exit.
99 *
100 * ```
101 * scip -f simple.lp
102 * ```
103 * reads and optimizes this model in no time:
104 *
105 * \verbinclude output.log
106 *
107 * @version 9.2.1
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 SRCORGA "Organization of source code"
343 * - @subpage OBJ "Creating, capturing, releasing, and adding data objects"
344 * - @subpage MEMORY "Using the memory functions of SCIP"
345 * - @subpage DEBUG "Debugging"
346 * - @subpage STAGES "SCIP stages"
347 */
348/**@page HOWTOADD How to add ...
349 *
350 * Below you find for most plugin types a detailed description of how to implement and add them to \SCIP.
351 *
352 * - @subpage CONS "Constraint handlers"
353 * - @subpage PRICER "Variable pricers"
354 * - @subpage PRESOL "Presolvers"
355 * - @subpage SEPA "Separators"
356 * - @subpage PROP "Propagators"
357 * - @subpage BRANCH "Branching rules"
358 * - @subpage CUTSEL "Cut selectors"
359 * - @subpage NODESEL "Node selectors"
360 * - @subpage HEUR "Primal heuristics"
361 * - @subpage DIVINGHEUR "Diving heuristics"
362 * - @subpage RELAX "Relaxation handlers"
363 * - @subpage READER "File readers"
364 * - @subpage DIALOG "Dialogs"
365 * - @subpage DISP "Display columns"
366 * - @subpage EVENT "Event handler"
367 * - @subpage EXPRHDLR "Expression handlers"
368 * - @subpage NLHDLR "Nonlinear handlers"
369 * - @subpage NLPI "Interfaces to NLP solvers"
370 * - @subpage EXPRINT "Interfaces to expression interpreters"
371 * - @subpage PARAM "additional user parameters"
372 * - @subpage TABLE "Statistics tables"
373 * - @subpage BENDER "Benders' decomposition"
374 * + @subpage BENDERSCUT "Benders' decomposition cuts"
375 */
376/**@page HOWTOUSESECTION How to use ...
377 *
378 * - @subpage CONF "Conflict analysis"
379 * - @subpage TEST "How to run automated tests with SCIP"
380 * - @subpage COUNTER "How to use SCIP to count feasible solutions"
381 * - @subpage REOPT "How to use reoptimization in SCIP"
382 * - @subpage CONCSCIP "How to use the concurrent solving mode in SCIP"
383 * - @subpage DECOMP "How to provide a problem decomposition"
384 * - @subpage BENDDECF "How to use the Benders' decomposition framework"
385 * - @subpage TRAINESTIMATION "How to train custom tree size estimation for SCIP"
386 * - @subpage SYMMETRY "How to use symmetry handling in SCIP"
387 * - @subpage PROBINGDIVING "How to use probing and diving mode"
388 */
389
390/**@page AUTHORS SCIP Authors
391 *
392 * A list of all current and former developers as well as contributors can
393 * be found on the
394 * <a class="el" href="http://scipopt.org/#developers">Main Web Page</a>.
395 *
396 */
397
398/**@page EXTERNALDOC Links to external documentation
399 *
400 * <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.
401 *
402 */
403
404/**@page CHG Release notes and changes between different versions of SCIP
405 *
406 * New features, peformance improvements, and interface changes between different versions of SCIP are documented in the
407 * release notes:
408 *
409 * - \subpage RN9 "SCIP 9"
410 * - \subpage RN8 "SCIP 8"
411 * - \subpage RN7 "SCIP 7.0"
412 * - \subpage RN6 "SCIP 6.0"
413 * - \subpage RN5 "SCIP 5.0"
414 * - \subpage RN4 "SCIP 4.0"
415 * - \subpage RN3_2 "SCIP 3.2"
416 * - \subpage RN3_1 "SCIP 3.1"
417 * - \subpage RN3_0 "SCIP 3.0"
418 * - \subpage RN2_1 "SCIP 2.1"
419 * - \subpage RN2_0 "SCIP 2.0"
420 * - \subpage RN1_2 "SCIP 1.2"
421 * - \subpage RN1_1 "SCIP 1.1"
422 * - \subpage RN1_0 "SCIP 1.0"
423 * - \subpage RN0_9 "SCIP 0.9"
424 * - \subpage RN0_8 "SCIP 0.8"
425 * - \subpage RN0_7 "SCIP 0.7"
426 *
427 */
428
429/**@page WHATPROBLEMS What types of optimization problems does SCIP solve?
430 *
431 * As a stand-alone solver, \SCIP can solve mixed-integer nonlinear programs \b (MINLPs), to which it applies
432 * an LP based spatial branch-and-cut algorithm. This method is guaranteed to solve bounded MINLPs
433 * within a given numerical tolerance in a finite amount of time. In particular, \SCIP is a stand-alone
434 * solver for mixed-integer linear programs \b (MIPs).
435 *
436 * As a framework, \SCIP also provides the tools to solve constraint optimization problems defined over
437 * integer and continuous variables. Therefore, the design of \SCIP
438 * supports the easy integration of constraints of arbitrary type into the solver.
439 * More precisely, \SCIP can handle the class of constraint integer programs \b (CIPs), which are constraint optimization problems
440 * that become linear programs (LPs) after the integer variables are fixed.
441 *
442 * @section PROBLEMCLASSES Some important subclasses of CIP and MINLP
443 *
444 * The following table gives a non-exhaustive list of common types of mathematical optimization problems that can be solved
445 * through \SCIP itself or one of its extensions. Some recommendations are given on how to compile \SCIP for a
446 * certain problem class and how make best use of \SCIP. The file format column gives some common file
447 * formats for every class. Note that since some of the mentioned problem classes are more general than others (like
448 * every LP is a MIP is an MINLP), the formats for the superclass should always work just as fine, although they
449 * may be less common for the class at hand.
450 *
451 * Please see also the pages on \ref EXAMPLES "SCIP Examples" and \ref APPLICATIONS "SCIP Applications" to learn more on how
452 * to extend \SCIP for a particular MIP, MINLP, or CIP application.
453 * All examples and applications use the C or C++ APIs of \SCIP. Please have a look at \ref INTERFACES "SCIP interfaces"
454 * to see how to use \SCIP from within other programming languages.
455 *
456 * <table class="types">
457 * <caption align="top">Some problem classes that can be solved by \SCIP</caption>
458 * <tr style="border-bottom: medium solid black;">
459 * <th>Problem class</th>
460 * <th>Mathematical problem description</th>
461 * <th>Supported file formats</th>
462 * <th>Recommendations</th>
463 * </tr>
464 * <tr>
465 * <td>Mixed-integer linear program (MIP)</td>
466 * <td>\f{align*}{
467 * \text{min} \quad& c^T x \\
468 * \text{s.t.} \quad& Ax \geq b \\
469 * &l_{j} \leq x_{j} \leq u_{j} && \forall j \in \mathcal{N} \\
470 * &x_{j} \in \mathbb{Z} && \forall j \in \mathcal{I}
471 * \f}
472 * </td>
473 * <td>
474 * <ul>
475 * <li>\ref reader_cip.h "CIP"</li>
476 * <li>\ref reader_mps.h "MPS"</li>
477 * <li>\ref reader_lp.h "LP"</li>
478 * <li>\ref reader_zpl.h "ZPL"</li>
479 * </ul>
480 * </td>
481 * <td>
482 * <ul>
483 * <li>\SCIP requires an external LP solver to solve LP relaxations, which needs to be specified
484 * at compilation time. By default, it uses SoPlex (<code>LPS=spx</code>). See \ref MAKE for a
485 * list of available LP solver interfaces and how to use them inside \SCIP.</li>
486 * <li>Compile with Zimpl support (<code>ZIMPL=true</code>) to read in Zimpl models directly.</li>
487 * <li>\SCIP comes with many different parameters. Use the provided emphasis settings (see \ref SHELL "this tutorial")
488 * to change many parameters at once and boost the performance.</li>
489 * <li>Test instances are available at <code>check/instances/MIP/</code>.</li>
490 * </ul>
491 * </td>
492 * </tr>
493 * <tr>
494 * <td>Mixed-integer nonlinear program (MINLP)</td>
495 * <td>\f{align*}{
496 * \text{min} \quad& f(x) \\
497 * \text{s.t.} \quad& g_{i}(x) \leq 0 && \forall i \in \mathcal{M} \\
498 * &l_{j} \leq x_{j} \leq u_{j} && \forall j \in \mathcal{N} \\
499 * &x_{j} \in \mathbb{Z} && \forall j \in \mathcal{I}
500 * \f}
501 * </td>
502 * <td>
503 * <ul>
504 * <li>\ref reader_cip.h "CIP"</li>
505 * <li>\ref reader_gms.h "GMS"</li>
506 * <li>\ref reader_osil.h "OSiL"</li>
507 * <li>\ref reader_pip.h "PIP"</li>
508 * <li>\ref reader_zpl.h "ZPL"</li>
509 * <li>For MIQCPS:
510 * <ul>
511 * <li>\ref reader_lp.h "LP"</li>
512 * <li>\ref reader_mps.h "MPS"</li>
513 * </ul>
514 * </li>
515 * </ul>
516 * </td>
517 * <td>
518 * <ul>
519 * <li>Compile with <code>IPOPT=true</code> for better performance.</li>
520 * <li>Compile with <code>WORHP=true</code> for better performance.</li>
521 * <li>Compile with <code>FILTERSQP=true</code> for better performance.</li>
522 * <li>See <a href="FAQ\FILEEXT#minlptypes"> Which kind of MINLPs are supported by \SCIP? </a> in the FAQ.</li>
523 * <li>There is an interface for the modelling language AMPL, see \ref INTERFACES.</li>
524 * <li>Mixed-integer quadratically constrained programs (MIQCP) can also be formulated in the file formats
525 * <ul>
526 * <li>\ref reader_lp.h "LP", and</li>
527 * <li>\ref reader_mps.h "MPS".</li>
528 * </ul>
529 * </li>
530 * <li>Test instances are available at <code>check/instances/MINLP/</code>.</li>
531 * </ul>
532 * </td>
533 * </td>
534 * <tr>
535 * <td>Constraint Integer Program (CIP)</td>
536 * <td>\f{align*}{
537 * \text{min} \quad& c^T x + d^T y \\
538 * \text{s.t.} \quad& C_i(x,y) = \text{true} && \forall i \in \mathcal{M} \\
539 * & x \in \mathbb{Z}^{p}, y \in \mathbb{R}^{n - p}
540 * \f}
541 * 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.
542 * </td>
543 * <td>
544 * <ul>
545 * <li>\ref reader_cip.h "CIP"</li>
546 * <li>\ref reader_fzn.h "FlatZinc"</li>
547 * </ul>
548 * </td>
549 * <td>
550 * <ul>
551 * <li>\SCIP supports a limited number of general constraints; see \ref CONS "How to add constraint handlers"
552 * to learn how to extend the \SCIP framework to a given CIP.</li>
553 * <li>Use the emphasis setting <code>set emphasis cpsolver</code> to completely disable LP solves and
554 * use depth-first search with periodic restarts, see also
555 * <a href="FAQ\FILEEXT#scipascpsolver"> Can I use \SCIP as a pure CP solver? </a> in the FAQ.</li>
556 * <li>Test instances are available at <code>check/instances/CP</code>.</li>
557 * </ul>
558 * </td>
559 * <tr>
560 * <td>Convex MINLP</td>
561 * <td>Like MINLP, \f$f\f$ and all \f$g_i\f$ are \b convex.</td>
562 * <td>see MINLP formats</td>
563 * <td>
564 * <ul>
565 * <li>See the comments for MINLP.</li>
566 * <li>In addition, use <code>constraints/nonlinear/assumeconvex = TRUE</code> to inform \SCIP about a convex
567 * problem in cases where the automated detection is not strong enough.</li>
568 * <li>Test instances are available at <code>check/instances/MINLP/circle.lp</code>.</li>
569 * </ul>
570 * </td>
571 * </td>
572 * <tr>
573 * <td>Linear program (LP)</td>
574 * <td>\f{align*}{
575 * \text{min} \quad& c^T x \\
576 * \text{s.t.} \quad& Ax \geq b \\
577 * & x_{j} \geq 0 && \forall j \in \mathcal{N}
578 * \f}
579 * </td>
580 * <td>see MIP formats</td>
581 * <td>See <a href="FAQ\FILEEXT#scipaslpsolver">Can I use \SCIP as a pure LP solver</a> in the FAQ.</td>
582 * </td>
583 * <tr>
584 * <td>Pseudoboolean optimization</td>
585 * <td>\f{align*}{
586 * \text{min} \quad& c^T x \\
587 * \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} \\
588 * &x_{j} \in \{0,1\} && \forall j \in \mathcal{N}
589 * \f}
590 * </td>
591 * <td>
592 * <ul>
593 * <li>\ref reader_wbo.h "WBO"</li>
594 * <li>\ref reader_opb.h "OPB"</li>
595 * </ul>
596 * </td>
597 * <td>
598 * <ul>
599 * <li>Test instances are available at <code>check/instances/PseudoBoolean/</code>.</li>
600 * </ul>
601 * </td>
602 * </tr>
603 * <tr>
604 * <td>Satisfiability (SAT) and variants</td>
605 * <td>\f{align*}{
606 * \text{min} \quad& 0 \\
607 * \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}\\
608 * &x_{j} \in \{\text{false},\text{true}\} && \forall j \in \mathcal{N}
609 * \f}
610 * </td>
611 * <td>
612 * <ul>
613 * <li>\ref reader_cnf.h "CNF"</li>
614 * </ul>
615 * </td>
616 * <td>
617 * <ul>
618 * <li>Use the emphasis setting <code>set emphasis cpsolver</code> to completely disable LP solves and
619 * use depth-first search with periodic restarts, see also
620 * <a href="FAQ\FILEEXT#scipascpsolver"> Can I use \SCIP as a pure CP/SAT solver? </a> in the FAQ.</li>
621 * <li>Test instances are available at <code>check/instances/SAT/</code>.</li>
622 * </ul>
623 * </td>
624 * </tr>
625 * <tr>
626 * <td>Multicriteria optimization</td>
627 * <td>\f{align*}{
628 * \text{min} \quad &(c_1^T x,\ldots,c_k^T x) \\
629 * \text{s.t. } \quad& Ax \geq b \\
630 * &x \in \mathbb{K}^n
631 * \f}
632 * where \f$\mathbb{K}\f$ is either \f$\mathbb{Z}\f$ or \f$\mathbb{R}\f$.
633 * </td>
634 * <td colspan="3"> see the <a href="http://polyscip.zib.de/">PolySCIP web page</a></td>
635 * </tr>
636 * <tr>
637 * <td>Mixed-integer semidefinite program (MISDP)</td>
638 * <td>\f{align*}{
639 * \text{inf} \quad \thinspace & b^T y \\
640 * \text{s.t.} \quad & \sum_{j=1}^m A_j\, y_j - A_0 \succeq 0 \\
641 * & y_j \in \mathbb{Z} && \forall\, j \in \mathcal{I}
642 * \f}
643 * </td>
644 * <td colspan="3"> see the <a href="http://www.opt.tu-darmstadt.de/scipsdp/">SCIP-SDP web page</a></td>
645 * </tr>
646 * </table>
647 *
648 *
649 */
650
651/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
652
653/**@page CODE Coding style guidelines
654 *
655 * We follow the following coding style guidelines and recommend them for all developers.
656 *
657 * @section CODESPACING Spacing:
658 *
659 * - Indentation is 3 spaces. No tabs anywhere in the code.
660 * - Every opening parenthesis requires an additional indentation of 3 spaces.
661 *
662 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleParenIndent}
663 *
664 * - Spaces around all operators.
665 * - Spaces around the arguments inside an if/for/while-statement, as well as inside macros (e.g., SCIP_CALL).
666 * - No spaces between control structure keywords like "if", "for", "while", "switch" and the corresponding brackets.
667 * - No spaces between a function name and the parenthesis in both the definition and function calls.
668 * - Braces are on a new line and not indented.
669 * - Braces in if/for-statements should only be omitted if they enclose a single line.
670 *
671 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleIfFor}
672 *
673 * - In function declarations, every parameter is on a new line. The name of the parameter starts at column 26,
674 * the comment starts at column 46 (if column-count starts with 1).
675 * - Maximal line length is 120 characters.
676 * - Always only one declaration in a line.
677 * - Variable names should be all lower case.
678 *
679 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleDeclaration}
680 *
681 * - Blank lines are inserted where it improves readability.
682 * - Multiple blank lines are used to structure the code where single blank lines are insufficient,
683 * e.g., between differrent sections of the code.
684 *
685 * @refsnippet{src/scip/heur_xyz.c,SnippetCodeStyleBlanks}
686 *
687 * @section CODENAMING Naming:
688 *
689 * - Use assert() to show preconditions for the parameters, invariants, and postconditions.
690 * - Make all functions that are not used outside the module 'static'.
691 * - Naming should start with a lower case letter.
692 *
693 * @refsnippet{src/scip/branch_relpscost.c,SnippetCodeStyleStaticAsserts}
694 *
695 * - All global functions start with "SCIP". In the usual naming scheme this is followed by the object and a method name
696 * like in SCIPlpAddRow(). Functions return TRUE or FALSE should be named like SCIPisFeasEQ().
697 *
698 * @refsnippet{src/scip/scip_numerics.h,SnippetCodeStyleNaming}
699 *
700 * - For each structure there is a typedef with the name in all upper case.
701 * - Defines should be named all upper case.
702 *
703 * @refsnippet{src/scip/type_set.h,SnippetCodeStyleExample}
704 *
705 * @section CODEDOC Documentation:
706 *
707 * - Document functions, parameters, and variables in a doxygen conformed way.
708 * - Please do not leave code in comments that has been commented out, don't use `#if
709 * 0`. Instead put the code within defines `#ifdef SCIP_DISABLED_CODE` and add an explanation.
710 * - Todos need double stars to be registered by doxygen.
711 * - When documenting methods, the first brief description starts with lower case and is separated by semi-colons, if necessary
712 * The longer description starts capitalized and consists of complete sentences.
713 * If the documentation consists of multiple lines, the comment end must be on a new line.
714 *
715 * @refsnippet{src/scip/scip_datastructures.h,SnippetCodeStyleComment}
716 *
717 *
718 * @section XEMACS Customize (x)emacs
719 *
720 * If you are using (x)emacs, you can use the following customization for the c++-mode. These settings satisfy the
721 * coding guidelines of \SCIP.
722 *
723 * \include codestyle/emacs_scip_codestyle.el
724 *
725 *
726 * @section ECLIPSE Customize eclipse
727 *
728 * Eclipse user can use the profile below. This profile does not match the \SCIP coding guideline completely.
729 *
730 * \include codestyle/eclipse_scip_codestyle.xml
731 */
732
733/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
734
735/**@page START How to start a new project
736 *
737 * Once you succeeded installing \SCIP together with an LP-solver on your system,
738 * you have a powerful tool for solving MIPs, MIQCPs,
739 * MINLPs, etc... at hand. \SCIP can also be customized to the type of problems you
740 * are working on by additional plugins.
741 * Instructions on how to write a new plugin and include it in \SCIP can be found in the corresponding
742 * \ref HOWTOADD "How to add ... pages".
743 *
744 * \SCIP can also be used for writing your own branch-and-cut or branch-and-cut-and-price code. \SCIP already
745 * provides a number of existing code examples which we suggest as both reference and starting point
746 * for these kinds of projects.
747 * Below, you find some hints of how to start such a project.
748 *
749 * @section START_CHOICE Choose an example project
750 *
751 * The example should be chosen depending on the programming language (<b>C</b> or <b>C++</b>) and the purpose
752 * (<b>branch-and-cut</b> or <b>branch-and-cut-and-price</b>) of your project.
753 * <br>
754 * We suggest the use of one of the following examples:
755 * - The \ref VRP_MAIN "Vehicle Routing Problem Example" is a <b>branch-and-cut-and-price</b> (column generation)-code
756 * in <b>C++</b>.
757 * - The \ref BINPACKING_MAIN "Binpacking Example"
758 * and the \ref COLORING_MAIN "Coloring application" are
759 * <b>branch-and-cut-and-price</b> (column generation)-codes in <b>C</b>.
760 * - The \ref TSP_MAIN "TSP example"
761 * is a <b>branch-and-cut</b>-code in <b>C++</b>.
762 * - The \ref LOP_MAIN "LOP example"
763 * is a <b>branch-and-cut</b>-code in <b>C</b>.
764 *
765 * More examples can be found in the \ref EXAMPLES "list of Examples".
766 *
767 * - Copy one of the examples in the <code>examples</code> directory (in the \SCIP root
768 * directory). For instance, type
769 * \verbatim
770 cp -r examples/Binpacking/ ../SCIPProject/ ; cd ../SCIPProject
771 \endverbatim
772 * from the \SCIP root directory for copying the content of the <code>Binpacking</code>-example into a fresh
773 * directory named SCIPProject in the parent directory of the \SCIP root directory and jumping to
774 * the new SCIPProject directory rightafter.
775 *
776 * @section START_CMAKE Building with CMake
777 *
778 * It is recommended for all new users to use the CMake build system configuration, if available on their platform.
779 *
780 * - Open the <code>CMakeLists</code> (some examples projects have a subdirectory "check" for testing) via
781 * \verbatim
782 kate CMakeLists.txt & kate check/CMakeLists.txt # if check/CMakeLists.txt is available
783 \endverbatim
784 * and replace all instances of the copied project's name (e.g. <code>binpacking</code>) with your project name.
785 * - Create a new subdirectory, jump to the new directory and use cmake specifying your \SCIP directory. For instance, type
786 * \verbatim
787 mkdir Release ; cd Release ; cmake .. -DSCIP_DIR=../scip/Release
788 \endverbatim
789 * 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.
790 *
791 *
792 * @section START_MAKE Building with the Makefile system
793 *
794 * If CMake should be unavailable on your targeted platform, try the classic Makefile system of SCIP.
795 *
796 * - Open the <code>Makefile</code> via
797 * \verbatim
798 kate Makefile
799 \endverbatim
800 * and edit the following variables at the top to have a compilable code:
801 *
802 * - specify a correct path to the \SCIP root (<code>SCIPDIR</code>)
803 * - rename the targets name (<code>MAINNAME</code>)
804 * - adjust the source file names (<code>MAINOBJ</code>).
805 * .
806 * - Once you have edited the makefile, you can use all the flags that can be used in \SCIP to
807 * compile your code, see \ref MAKE.
808 *
809 */
810
811/**@page EXAMPLES Example projects
812 *
813 * \SCIP contains several examples that demonstrate its usage. They are contained in the &quot;examples&quot; directory
814 * in the source code distribution.
815 *
816 * <table>
817 * <tr>
818 * <td colspan="2">
819 * <b>
820 * Callable library
821 * </b>
822 * </td>
823 * </tr>
824 * <tr>
825 * <td>
826 * @subpage CALLABLELIBRARY_MAIN "Callable Library Example"
827 * </td>
828 * <td>
829 * An example showing how to setup constraints (esp. nonlinear ones) when using \SCIP as callable library.
830 * </td>
831 * </tr>
832 * <tr>
833 * <td>
834 * @subpage MIPSOLVER_MAIN "MIP solver"
835 * </td>
836 * <td>
837 * A minimal implementation for using \SCIP included into another source code
838 * </td>
839 * </tr>
840 * <tr>
841 * <td>
842 * @subpage QUEENS_MAIN "The n-Queens Problem"
843 * </td>
844 * <td>
845 * Using SCIP's callable library for solving the n-queens problem.
846 * </td>
847 * </tr>
848 * <tr>
849 * <td colspan="2">
850 * <b>
851 * Extending SCIP by custom plugins
852 * </b>
853 * </td>
854 * </tr>
855 * <tr>
856 * <td>
857 * @subpage EVENTHDLR_MAIN "Event handler"
858 * </td>
859 * <td>
860 * A small example illustrating the use of an event handler.
861 * </td>
862 * </tr>
863 * <tr>
864 * <td>
865 * @subpage GMI_MAIN "Gomory mixed integer cut example"
866 * </td>
867 * <td>
868 * An example about Gomory mixed-integer cuts.
869 * </td>
870 * </tr>
871 * <tr>
872 * <td>
873 * @subpage RELAXATOR_MAIN "Relaxator example"
874 * </td>
875 * <td>
876 * An example about using custom relaxators.
877 * </td>
878 * </tr>
879 * <tr>
880 * <td colspan="2">
881 * <b>
882 * Branch-and-cut
883 * </b>
884 * </td>
885 * </tr>
886 * <tr>
887 * <td>
888 * @subpage SUDOKU_MAIN "Sudoku example"
889 * </td>
890 * <td>
891 * An example solving sudokus.
892 * </td>
893 * </tr>
894 * <tr>
895 * <td>
896 * @subpage LOP_MAIN "Linear Ordering"
897 * </td>
898 * <td>
899 * An example for implementing a constraint handler.
900 * </td>
901 * </tr>
902 * <tr>
903 * <td>
904 * @subpage TSP_MAIN "The TSP example"
905 * </td>
906 * <td>
907 * A short implementations of a constraint handler, two easy combinatorial heuristics, a file reader, etc. which
908 * demonstrate the usage of \SCIP as a branch-and-cut-framework for solving traveling salesman problem instances.
909 * </td>
910 * </tr>
911 * <tr>
912 * <td colspan="2">
913 * <b>
914 * Branch-and-price
915 * </b>
916 * </td>
917 * </tr>
918 * <tr>
919 * <td>
920 * @subpage BINPACKING_MAIN "Binpacking"
921 * </td>
922 * <td>
923 * An implementation of the column generation approach for the binpacking problem. It includes a customized reader,
924 * Ryan/Foster branching rule, (global) problem data, variable data, and constraint handler.
925 * </td>
926 * </tr>
927 * <tr>
928 * <td>
929 * @subpage VRP_MAIN "Vehicle Routing"
930 * </td>
931 * <td>
932 * A solver for a simple capacity-constrained vehicle routing problem, which is based on pricing tours via a dynamic
933 * programming algorithm.
934 * </td>
935 * </tr>
936 * <tr>
937 * <td colspan="2">
938 * <b>
939 * Benders' decomposition
940 * </b>
941 * </td>
942 * </tr>
943 * <tr>
944 * <td>
945 * @subpage SCFLP_MAIN "Stochastic capacitated facility location problem"
946 * </td>
947 * <td>
948 * A stochastic programming problem that demonstrates the use of the Benders' decomposition framework within SCIP.
949 * </td>
950 * </tr>
951 * </table>
952 */
953
954/** @page APPLICATIONS Application projects
955 *
956 * There are several extensions of \SCIP for particular applications included in the release. They are contained in the &quot;applications&quot; directory
957 * in the source code distribution.
958 *
959 * <table>
960 * <tr>
961 * <td>
962 * @subpage COLORING_MAIN
963 * </td>
964 * <td>
965 * An implementation of the column generation approach for graph coloring of Mehrotra and Trick.
966 * </td>
967 * </tr>
968 * <tr>
969 * <td>
970 * @subpage CYCLECLUSTERING_MAIN
971 * </td>
972 * <td>
973 * Branch-and-cut implementation of a graph partitioning problem used for Markov state models.
974 * </td>
975 * </tr>
976 * <tr>
977 * <td>
978 * @subpage MINIISC_MAIN
979 * </td>
980 * <td>
981 * A solver that computes irreducible infeasible subsystems using Benders decomposition
982 * </td>
983 * </tr>
984 * <tr>
985 * <td>
986 * @subpage RINGPACKING_MAIN "Ringpacking"
987 * </td>
988 * <td>
989 * An implementation of the column generation approach for the Ringpacking Problem. It includes a customized reader,
990 * (global) problem data, variable data, and constraint handler.
991 * </td>
992 * </tr>
993 * <tr>
994 * <td>
995 * @subpage SCHEDULER_MAIN
996 * </td>
997 * <td>
998 * A solver for scheduling problems.
999 * </td>
1000 * </tr>
1001 * </table>
1002 *
1003 */
1004
1005
1006/**@page SHELL Tutorial: the interactive shell
1007 *
1008 * If you are using \SCIP as a black box solver, here you will find some tips and tricks what you can do.
1009 *
1010 * @section TUTORIAL_OPTIMIZE Read and optimize a problem instance
1011 *
1012 * @subsection SHELL_PREREQUISITES "Prerequisites"
1013 *
1014 * First of all, we need a \SCIP binary and an example problem file to work with.
1015 * For installation we refer you to the \ref INSTALL section.
1016 *
1017 * Therefore, you can either download the \SCIP standard distribution (which includes problem files) and compile it on your own or you can download a
1018 * precompiled binary and an example problem separately. \SCIP can read files in LP, MPS, ZPL, WBO, FZN, PIP, OSiL, and
1019 * other formats (see \ref FILEREADERS).
1020 *
1021 * If you want to download the source code of the \SCIP standard distribution, we recommend to go to the <a
1022 * href="https://scipopt.org/#download">SCIP download section</a>, download the latest release,
1023 * inflate the tarball (e.g., with "tar xzf scipoptsuite-[version].tgz"), and follow the instructions
1024 * in the INSTALL file. The instance stein27, which will serve as an example in this tutorial, can be found under
1025 * scipoptsuite-[version]/scip-[version]/check/instances/MIP/stein27.fzn.
1026 * Alternatively you can download an instance file from the <a href="https://miplib.zib.de/tag_benchmark.html">MIPLIB 2017 page</a>.
1027 *
1028 * If you want to download a precompiled binary, go to the <a href="http://scipopt.org/#download">SCIP download
1029 * section</a> and download an appropriate binary for your operating system. The \SCIP source code distribution already comes with
1030 * the example instance used throughout this tutorial. To follow this tutorial with a precompiled binary, we recommend downloading the instance
1031 * <a href="http://miplib2010.zib.de/miplib3/miplib3/stein27.mps.gz">stein27</a> from
1032 * the <a href="http://miplib2010.zib.de/miplib3/miplib.html">MIPLIB 3.0</a> homepage.
1033 *
1034 * @subsection SHELL_AFTERINSTALL "After installation"
1035 *
1036 * Now start your binary, without any arguments. This opens the interactive shell, which should look somehow like this:
1037 *
1038 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetVersion
1039 *
1040 * First of all "help" shows you a list of all available shell commands. Brackets indicate a submenu with further options.
1041 *
1042 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetHelp
1043 *
1044 * 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
1045 * solution" to show the nonzero variables of the best found solution.
1046 *
1047 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetOpt1
1048 *
1049 * What do we see here? After "optimize", SCIP first goes into presolving. Not much is happening for this instance, just
1050 * the linear constraints get upgraded to more specific types. Each round of presolving will be displayed in a single
1051 * line, with a short summary at the end. Then, we see the actual solving process. The table output of the branch-and-cut
1052 * solving process is very detailed during the root node. Afterwards, a new line is displayed every 100th node.
1053 * Furthermore, every new incumbent solution triggers a new table row, starting with a character to indicate the
1054 * heuristic that found the solution. Which letter represents which heuristic can be seen with the
1055 * "display heuristics" command, see \ref TUTORIAL_STATISTICS for an example.
1056 *
1057 * After some lines the root node processing is finished. From now on, we will see an output line every hundredth node or
1058 * whenever a new incumbent is found. After some more nodes, the "dualbound" starts
1059 * moving, too. At one point, both will be the same, and the solving process terminates, showing us some wrap-up
1060 * information.
1061 *
1062 * The exact performance may of course vary among different architectures and operating systems. Do not be worried if
1063 * your installation needs more or less time or nodes to solve. Also, this instance has more than 2000 different optimal
1064 * solutions. The optimal objective value always has to be 18, but the solution vector may differ. If you are interested
1065 * in this behavior, which is called "performance variability", you may have a look at the MIPLIB2010 paper.
1066 *
1067 * @section TUTORIAL_FILEIO Writing problems and solutions to a file
1068
1069 * \SCIP can also write information to files. E.g., we could store the incumbent solution to a file, or output the
1070 * problem instance in another file format (the LP format is much more human readable than the MPS format, for example).
1071 *
1072 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetWriteSolutions
1073 *
1074 * Passing starting solutions can increase the solving performance so that \SCIP does not need to construct an initial feasible solution
1075 * by itself. After reading the problem instance, use the "read" command again, this time with a file containing solution information.
1076 * Solutions can be specified in a raw or xml-format and must have the file extension ".sol", see the documentation of the
1077 * \ref reader_sol.h "solution reader of SCIP" for further information.
1078 *
1079 * Customized settings are not written or read with the "write" and "read" commands, but with the three commands
1080 *
1081 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSaveSettingsOverview
1082 *
1083 * See the section on parameters \ref TUTORIAL_PARAMETERS for more information.
1084 *
1085 * @section TUTORIAL_STATISTICS Displaying detailed solving statistics
1086 *
1087 * We might want to have some more information now. Which of the heuristics found solutions? Which plugins
1088 * were called during the solutions process and how much time did they spend?
1089 * Information on certain plugin types (e.g., heuristics, branching rules, separators) is displayed via
1090 * "display <plugin-type>", information on the solution process via "display statistics", and "display problem"
1091 * shows the current instance.
1092 *
1093 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetDisplayStatistics
1094 *
1095 * The statistics obtained via "display statistics" are quite comprehensive,
1096 * thus, we just explain a few lines here. Information is grouped by the plugin type. For the primal heuristics,
1097 * the execution time in seconds is shown as well as the number of calls to the heuristic, and its success regarding
1098 * the number of (best) solutions found by that heuristic. Appropriate statistics are also shown for presolvers, constraint handlers,
1099 * separators, propagators, the search tree, etc. User-written plugins will appear automatically in these statistics,
1100 * after they were included into \SCIP.
1101 *
1102 * @section TUTORIAL_PARAMETERS Changing parameters from the interactive shell
1103 *
1104 * Now, we can start playing around with parameters. The primal heuristics Rounding and shifting seem to be quite successful on this instance,
1105 * wondering what happens if we disable them? Or what happens, if we are even more rigorous and disable all heuristics?
1106 * Or if we do the opposite and use aggressive heuristics?
1107 *
1108 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSetSettings
1109 *
1110 * We can navigate through the menus step-by-step and get a list of available options and submenus. Therefore, we select
1111 * "set" to change settings, "heuristics" to change settings of primal heuristics, and "shifting" for that particular
1112 * heuristic. Then we see a list of parameters (and yet another submenu for advanced parameters), and disable this
1113 * heuristic by setting its calling frequency to -1. If we already know the path to a certain setting, we can directly
1114 * type it (as for the rounding heuristic in the above example). Note that we do not have to use the full names, but we
1115 * may use short versions, as long as they are unique.
1116 *
1117 * To solve a problem a second time, we have to read it in again before starting the optimization process.
1118 *
1119 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetOpt2
1120 *
1121 * Okay, what happened here? First, we reset all parameters to their default values, using "set default". Next, we
1122 * loaded some meta-parameter settings (also see <a href="FAQ.php#howtochangebehaviour">the FAQ</a>), to apply primal heuristics
1123 * more aggressively. \SCIP shows us, which single parameters it changed therefore. Additionally, for pedagogical purposes,
1124 * we set the node limit to 200. Now, the optimal solution is already found at the root node, by a heuristic which is
1125 * deactivated by default. Then, after node 200, the user defined node limit is reached which interrupts the solving
1126 * process, We see that now in the short status report, primal and dual bound are different, thus, the problem is not solved
1127 * yet. Nevertheless, we could access statistics, see the current incumbent solution, change parameters and so on.
1128 * Entering "optimize" we continue the solving process from the point on at which it has been interrupted.
1129 *
1130 * Once you found a non-default parameter setting that you wish to save and use in the future, use either the command
1131 *
1132 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSaveSettingsFull
1133 *
1134 * to save <b>all</b> parameter values to the specified file, or
1135 *
1136 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetSaveSettingsDiff
1137 *
1138 * in order to save only the nondefault parameters. The latter has several advantages, you can, e.g., combine parameter
1139 * settings from multiple settings files stored by the latter command, as long as they only affect mutually exclusive
1140 * parameter values.
1141 *
1142 * For loading a previously stored settings file, use the "load" command:
1143 *
1144 * @snippet shelltutorial/shelltutorialannotated.tmp SnippetLoadSettings
1145 *
1146 * Special attention should be drawn to the reserved settings file name "scip.set"; whenever the \SCIP interactive shell
1147 * is started from a working directory that contains a settings file with the name "scip.set", it will be automatically
1148 * replace the default settings.
1149 *
1150 * For using special settings for automated tests as described in \ref TEST, save your custom settings in a subdirectory
1151 * "SCIP_HOME/settings".
1152 *
1153 *
1154 * We hope this tutorial gave you an overview of what is possible using the \SCIP interactive shell. Please also read our
1155 * \ref FAQ, in particular the section "Using SCIP as a standalone MIP/MINLP-Solver".
1156 *
1157 */
1158
1159/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
1160
1161/**@page DOC How to search the documentation and source files structure for public interface methods
1162 *
1163 * 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.
1164 * - It contains interface methods for all SCIP structs, both in the solver core or in one of the plugins.
1165 * - Plugins are mostly independent from each other, so to use them it is usually enough to browse the \ref PUBLICCOREAPI "Core API".
1166 * - If you want to add your own plugins, see the \ref HOWTOADD pages for exhaustive information for each plugin type.
1167 * - If you are learning SCIP with a concrete project in mind, looking at the available \ref EXAMPLES page may help you
1168 * getting started.
1169 * - See also \ref START "How to start a new project"
1170 *
1171 * 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_",
1172 * such as \ref type_var.h , which contains enums and type definitions related to \ref PublicVariableMethods "SCIP problem variables".
1173 * Definitions of the actual structs can be found in separate header files starting with "struct_".
1174 * All method definitions of the public SCIP API are split across header files starting with "pub_" such as \ref pub_cons.h
1175 * or headers starting with "scip_" such as \ref scip_cons.h .
1176 * The latter headers starting with "scip_" contain more complex methods, which always receive a scip pointer as first argument.
1177 * Those methods may affect several individual components controlled by SCIP. Such a method is SCIPbranchVar(), which
1178 * affects the search tree, which is controlled by SCIP itself and not meant to be accessed by user plugins.
1179 *
1180 * It should be sufficient to include scip/scip.h and scip/scipdefplugins.h for having all
1181 * needed functionality available in a project.
1182 *
1183 * If, for example, you are looking for information on how to create a problem instance, here are some steps you can take:
1184 *
1185 * 1. Browse the SCIP Core API and follow the path \ref PUBLICAPI > \ref PUBLICCOREAPI > \ref PublicProblemMethods > \ref GlobalProblemMethods > SCIPcreateProb()
1186 * 2. Here you can find information on the function's return value, preconditions, postconditions, parameters, as well as related functions.
1187 * 3. If you are unsure of how to use some of the parameters, it is worth looking for a basic version of the function.
1188 * 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
1189 * 'References' and 'Referenced by' section of the function documentation. In this case, you can find `SCIPcreateProbBasic()`.
1190 *
1191 * The opposite case is that you already know the name of a function as, e.g., SCIPbranchVar().
1192 *
1193 * 1. Type the name of the function into the search bar to find the function documentation.
1194 * 2. In addition, you can find related methods by browsing the neighboring functions of the same group.
1195 * 3. In this example, you may now learn about SCIPgetNLPBranchCands() to query all integer
1196 * variables with fractional LP solution value, which are good candidates for classical branching on variables.
1197 *
1198 * Note that the \ref INTERNALAPI "private SCIP API" contains more complex functions and data structures that fill specialized roles and
1199 * is only for developers.
1200 * Those functions are **not** exported to the library and are therefore **not available in user projects** using the \ref PUBLICAPI "public SCIP API".
1201 */
1202
1203/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
1204
1205/**@page CONS How to add constraint handlers
1206 *
1207 * A constraint handler defines the semantics and the algorithms to process constraints of a certain class. A single
1208 * constraint handler is responsible for all constraints belonging to its constraint class. For example, there is
1209 * one \ref cons_knapsack.h "knapsack constraint handler" that ensures solutions are only accepted if they satisfy all
1210 * knapsack constraints in the model. \n A complete list of all constraint handlers contained in this release can be
1211 * found \ref CONSHDLRS "here".
1212 *
1213 * We now explain how users can add their own constraint handlers.
1214 * For an example, look into the subtour constraint handler (examples/TSP/src/ConshdlrSubtour.cpp) of the
1215 * \ref TSP_MAIN project.
1216 * The example is written in C++ and uses the C++ wrapper classes.
1217 * However, we will explain the implementation of a constraint handler using the C interface.
1218 * It is very easy to transfer the C explanation to C++; whenever a method should be implemented using the
1219 * SCIP_DECL_CONS... notion, reimplement the corresponding virtual member function of the abstract scip::ObjConshdlr
1220 * base class.
1221 *
1222 * Additional documentation for the callback methods of a constraint handler can be found in the file
1223 * type_cons.h.
1224 *
1225 * Here is what you have to do (assuming your constraint handler should be named "subtour"):
1226 * -# Copy the template files src/scip/cons_xyz.c and src/scip/cons_xyz.h into files "cons_subtour.c"
1227 * and "cons_subtour.h".
1228 * \n
1229 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
1230 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
1231 * -# Use `SCIPincludeConshdlrSubtour()` in order to include the constraint handler into your SCIP instance,
1232 * e.g., in the main file of your project (see, e.g., src/cppmain.cpp in the TSP example). \n
1233 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
1234 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "subtour".
1235 * -# Adjust the \ref CONS_PROPERTIES "properties of the constraint handler".
1236 * -# Define the \ref CONS_DATA "constraint data and the constraint handler data". This is optional.
1237 * -# Implement the \ref CONS_INTERFACE "interface methods".
1238 * -# Implement the \ref CONS_FUNDAMENTALCALLBACKS "fundamental callback methods".
1239 * -# Implement the \ref CONS_ADDITIONALCALLBACKS "additional callback methods". This is optional.
1240 *
1241 *
1242 * @section CONS_PROPERTIES Properties of a Constraint Handler
1243 *
1244 * At the top of the new file "cons_subtour.c" you can find the constraint handler properties.
1245 * These are given as compiler defines. Some of them are optional, as, e.g., separation-related properties,
1246 * which only have to be defined if the constraint handler supports the related callbacks.
1247 * In the C++ wrapper class, you have to provide the constraint handler properties by calling the constructor
1248 * of the abstract base class scip::ObjConshdlr from within your constructor (see the TSP example).
1249 * The properties you have to set have the following meaning:
1250 *
1251 * @subsection CONS_FUNDAMENTALPROPERTIES Fundamental Constraint Handler properties
1252 *
1253 * \par CONSHDLR_NAME: the name of the constraint handler.
1254 * This name is used in the interactive shell to address the constraint handler.
1255 * Additionally, if you are searching for a constraint handler with SCIPfindConshdlr(), this name is looked up.
1256 * Names have to be unique: no two constraint handlers may have the same name.
1257 *
1258 * \par CONSHDLR_DESC: the description of the constraint handler.
1259 * This string is printed as a description of the constraint handler in the interactive shell of SCIP.
1260 *
1261 * \par CONSHDLR_ENFOPRIORITY: the priority of the constraint handler for constraint enforcing.
1262 * Like the separation priority, the enforcement priorities define the order in which the different constraint handlers
1263 * are called in the constraint enforcement step of the subproblem processing.
1264 * The constraint enforcement is called after the price-and-cut loop is executed (in the case that the LP is solved
1265 * at the current subproblem).
1266 * \n
1267 * The integrality constraint handler has an enforcement priority of 0.
1268 * That means, if a constraint handler has negative enforcement priority, it only has to deal with integral solutions
1269 * in its enforcement methods, because for fractional solutions, the integrality constraint handler would have
1270 * created a branching, thereby aborting the enforcement step.
1271 * If you want to implement a constraint-depending branching rule (for example, SOS branching on special ordered
1272 * set constraints), you have to assign a positive enforcement priority to your constraint handler.
1273 * In this case, you have to be able to deal with fractional solutions.
1274 * \n
1275 * See \ref CONSENFOLP and \ref CONSENFOPS for further details of the separation callback.
1276 *
1277 * \par CONSHDLR_CHECKPRIORITY: the priority of the constraint handler for checking feasibility.
1278 * Like the separation priority, the checking priorities define the order in which the different constraint handlers
1279 * are called to check the feasibility of a given primal solution candidate.
1280 * The integrality constraint handler has a checking priority of 0.
1281 * That means, constraint handlers with negative checking priorities only have to deal with integral solutions.
1282 *
1283 * \par CONSHDLR_EAGERFREQ: the default frequency for using all instead of only the useful constraints in separation, propagation and enforcement.
1284 * If \em constraint \em aging is activated, some constraints that were not useful in the past for propagation or
1285 * separation are marked to be \em obsolete.
1286 * Usually, the obsolete constraints are not presented to the separation and propagation methods of the constraint
1287 * handlers, such that the constraint handlers only process the non-obsolete constraints.
1288 * However, every n'th call, with n being the EAGERFREQ of the constraint handler, all constraints are presented to the
1289 * separation and propagation methods of the constraint handler.
1290 * This gives obsolete constraints the chance of becoming non-obsolete again.
1291 * \n
1292 * If the eager evaluation frequency is set to -1, obsolete constraints are never presented to the separation and
1293 * propagation methods.
1294 * A frequency of 0 means, that obsolete constraints are only used in the first call of each method.
1295 *
1296 * \par CONSHDLR_NEEDSCONS: indicates whether the constraint handler should be skipped, if no constraints are available.
1297 * Usually, a constraint handler is only executed if there are constraints of its corresponding class in the model.
1298 * For those constraint handlers, the NEEDSCONS flag should be set to TRUE.
1299 * However, some constraint handlers must be called without having a constraint of the class in the model, because
1300 * the constraint is only implicitly available.
1301 * For example, the integrality constraint handler has the NEEDSCONS flag set to FALSE, because there is no explicit
1302 * integrality constraint in the model.
1303 * The integrality conditions are attached to the variables, and the integrality constraint handler has to check
1304 * all variables that are marked to be integer for integral values.
1305 *
1306 * @subsection CONS_ADDITIONALPROPERTIES Optional Constraint Handler properties
1307 *
1308 * The following properties are optional and only need to be defined if the constraint handlers support
1309 * separation, presolving, propagation, and/or upgrade functionality.
1310 *
1311 * \par LINCONSUPGD_PRIORITY: priority of the constraint handler for upgrading of linear constraints
1312 * This property is only needed if a certain linear constraint can be upgraded to a more specific one. In one of
1313 * the first presolving rounds SCIP tries to upgrade linear constraints to more specialized constraints, such as
1314 * knapsack constraints. The upgrading calls are processed in the order of decreasing priority.
1315 *
1316 * \par NONLINCONSUPGD_PRIORITY: priority of the constraint handler for upgrading of nonlinear constraints
1317 * This property has the same effect as the LINCONSUPGD_PRIORITY parameter, see above, and should be set whenever
1318 * an upgrade functionality from a general nonlinear constraint to the more specific one is defined.
1319 *
1320 * \par CONSHDLR_SEPAFREQ: the default frequency for separating cuts.
1321 * The separation frequency defines the depth levels at which the constraint handler's separation methods \ref CONSSEPALP
1322 * and \ref CONSSEPASOL are called.
1323 * For example, a separation frequency of 7 means, that the separation callback is executed for subproblems that are
1324 * in depth 0, 7, 14, ... of the branching tree.
1325 * A separation frequency of 0 means, that the separation method is only called at the root node.
1326 * A separation frequency of -1 disables the separation method of the constraint handler.
1327 * \n
1328 * The separation frequency can be adjusted by the user.
1329 * This property of the constraint handler only defines the default value of the frequency.
1330 * If you want to have a more flexible control of when to execute the separation algorithm, you have to assign
1331 * a separation frequency of 1 and implement a check at the beginning of your separation algorithm whether you really
1332 * want to execute the separator or not.
1333 * If you do not want to execute the method, set the result code to SCIP_DIDNOTRUN.
1334 *
1335 * \par CONSHDLR_SEPAPRIORITY: the priority of the constraint handler for separation. (optional: to be set only if the constraint handler supports separation)
1336 * In each separation round during the price-and-cut loop of the subproblem processing or during the separation loop
1337 * of the primal solution separation, the separators and separation methods of the constraint handlers are called in
1338 * a predefined order, which is given by the priorities of the separators and the separation priorities of the
1339 * constraint handlers.
1340 * First, the separators with non-negative priority are called in the order of decreasing priority.
1341 * Next, the separation methods of the different constraint handlers are called in the order of decreasing separation
1342 * priority.
1343 * Finally, the separators with negative priority are called in the order of decreasing priority.
1344 * \n
1345 * The separation priority of the constraint handler should be set according to the complexity of the cut separation
1346 * algorithm and the impact of the resulting cuts:
1347 * Constraint handlers that provide fast algorithms that usually have a high impact (i.e., cut off a large portion of
1348 * the LP relaxation) should have a high priority.
1349 * See \ref CONSSEPALP and \ref CONSSEPASOL for further details of the separation callbacks.
1350 *
1351 * \par CONSHDLR_DELAYSEPA: the default for whether the separation method should be delayed, if other separators found cuts.
1352 * If the constraint handler's separation method is marked to be delayed, it is only executed after no other separator
1353 * or constraint handler found a cut during the price-and-cut loop.
1354 * If the separation method of the constraint handler is very expensive, you may want to mark it to be delayed until all
1355 * cheap separation methods have been executed.
1356 *
1357 * \par CONSHDLR_PROPFREQ: the default frequency for propagating domains.
1358 * This default frequency has the same meaning as the CONSHDLR_SEPAFREQ with respect to the domain propagation
1359 * callback of the constraint handler.
1360 * A propagation frequency of 0 means that propagation is only applied in preprocessing and at the root node.
1361 * A propagation frequency of -1 disables the propagation method of the constraint handler.
1362 *
1363 * \par CONSHDLR_DELAYPROP: the default for whether the propagation method should be delayed, if other propagators found reductions.
1364 * This property is analogous to the DELAYSEPA flag, but deals with the propagation method of the constraint handler.
1365 *
1366 * \par CONSHDLR_PROP_TIMING: the propagation timing mask of the constraint handler.
1367 * SCIP calls the domain propagation routines at different places in the node processing loop.
1368 * This property indicates at which places the propagation routine of the constraint handler is called.
1369 * Possible values are defined in type_timing.h and can be concatenated, e.g., as in SCIP_PROPTIMING_ALWAYS.
1370 *
1371 * \par CONSHDLR_PRESOLTIMING: the timing of the constraint handler's presolving method (FAST, MEDIUM, or EXHAUSTIVE).
1372 * Every presolving round starts with the FAST presolving methods. MEDIUM presolvers are only called, if FAST presolvers did not find
1373 * enough reductions in this round so far, and EXHAUSTIVE presolving steps are only performed if all presolvers called before
1374 * in this round were unsuccessful.
1375 * Presolving methods should be assigned a timing based on how expensive they are, e.g., presolvers that provide fast algorithms that
1376 * usually have a high impact (i.e., remove lots of variables or tighten bounds of many variables) should have a timing FAST.
1377 * If a presolving method implements different algorithms of different complexity, it may also get multiple timings and check the timing
1378 * internally in the \ref CONSPRESOL callback to decide which algorithms to run.
1379 *
1380 * \par CONSHDLR_MAXPREROUNDS: the default maximal number of presolving rounds the constraint handler participates in.
1381 * The preprocessing is executed in rounds.
1382 * If enough changes have been applied to the model, an additional preprocessing round is performed.
1383 * The MAXPREROUNDS parameter of a constraint handler denotes the maximal number of preprocessing rounds the constraint
1384 * handler participates in.
1385 * A value of -1 means that there is no limit on the number of rounds.
1386 * A value of 0 means the preprocessing callback of the constraint handler is disabled.
1387 *
1388 *
1389 *
1390 * @section CONS_DATA Constraint Data and Constraint Handler Data
1391 *
1392 * Below the header "Data structures" you can find two structs called "struct SCIP_ConsData" and
1393 * "struct SCIP_ConshdlrData".
1394 * If you are using C++, you only need to define the "struct SCIP_ConsData".
1395 * The constraint handler data must be implemented as member variables of your constraint handler class.
1396 * \n
1397 * The constraint data are the information that is needed to define a single constraint of the constraint handler's
1398 * constraint class.
1399 * For example, the data of a knapsack constraint would consist of a list of variables, a list of weights, and
1400 * the capacity of the knapsack.
1401 * The data of a subtour constraint consists of the graph on which the problem is defined.
1402 * In the graph, each edge should be linked to the corresponding binary problem variable.
1403 * \n
1404 * The constraint handler data are additional variables, that belong to the constraint handler itself and which are
1405 * not specific to a single constraint.
1406 * For example, you can use these data to store parameters of the constraint handler or statistical information.
1407 * The constraint handler data are optional.
1408 * You can leave the struct empty.
1409 *
1410 *
1411 * @section CONS_INTERFACE Interface Methods
1412 *
1413 * At the bottom of "cons_subtour.c" you can find three interface methods, that also appear in "cons_subtour.h".
1414 * These are SCIPincludeConshdlrSubtour(), SCIPcreateConsSubtour(), and SCIPcreateConsSubtourBasic().
1415 * \n
1416 * The method SCIPincludeConshdlrSubtour() only has to be adjusted slightly.
1417 * It is responsible for notifying SCIP of the presence of the constraint handler by calling the method
1418 * SCIPincludeConshdlr().
1419 * It is called by the user, if (s)he wants to include the constraint handler, i.e., if (s)he wants to make
1420 * the constraint handler available to the model, and looks like this:
1421 * \dontinclude src/scip/cons_knapsack.c
1422 * -# If you are using constraint handler data, you have to <b>allocate the memory for the data</b> at this point.
1423 * You also have to initialize the fields in struct SCIP_ConshdlrData afterwards.
1424 *
1425 * \skip SCIP_RETCODE SCIPincludeConshdlrKnapsack(
1426 * \until SCIPallocBlockMemory
1427 *
1428 * -# Now, <b>SCIP gets notified</b> of the presence of the constraint handler together with its \ref CONS_FUNDAMENTALCALLBACKS "basic callbacks".
1429 *
1430 * \skip SCIPincludeConshdlrBasic
1431 * \until assert
1432 *
1433 * -# All \ref CONS_ADDITIONALCALLBACKS "additional callbacks" are added via their setter functions.
1434 *
1435 * \skip SCIPsetConshdlrCopy
1436 * \until SCIPsetConshdlrExit
1437 *
1438 * -# If the constraint handler is a specialization of a general linear or nonlinear constraint, we want to include an
1439 * <b>automatic upgrading mechanism</b> by calling the interface method
1440 *
1441 * \skip SCIPfindConshdlr
1442 * \until SCIPincludeLinconsUpgrade
1443 * or
1444 * \code
1445 * SCIP_CALL( SCIPincludeNonlinconsUpgrade(scip, nonlinconsUpgdSubtour, NULL, NONLINCONSUPGD_PRIORITY, TRUE, CONSHDLR_NAME) );
1446 * \endcode
1447 *
1448 * in the nonlinear case. See also cons_nonlinear.h for further information about the general upgrade procedure in the nonlinear case.
1449 * -# You may also add <b>user parameters</b> for your constraint handler.
1450 * Some parameters which are important to play with are added to every constraint automatically, as, e.g.,
1451 * propagation or separation frequency.
1452 * \skip SCIPaddIntParam
1453 * \until DEFAULT_SEPACARDFREQ
1454 * \skip SCIP_OKAY
1455 * \until }
1456 *
1457 *
1458 * The methods SCIPcreateConsSubtour() and SCIPcreateConsSubtourBasic() are called to create a single constraint of the constraint
1459 * handler's constraint class.
1460 * It should allocate and fill the constraint data, and call SCIPcreateCons().
1461 * Take a look at the following example from the \ref cons_knapsack.h "knapsack constraint handler":
1462 *
1463 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsCreationKnapsack}
1464 *
1465 * In this example, consdataCreate() is a local method that allocates memory for the given consdata
1466 * and fills the data with the given <code>vars</code> array. For allocating memory for the constraint data, you
1467 * can use SCIP memory allocation:
1468 * \code
1469 * SCIP_CALL( SCIPallocBlockMemory(scip, consdata) );
1470 * \endcode
1471 *
1472 *
1473 * @section CONS_CALLBACKS Callback methods of Constraint handlers
1474 *
1475 * Besides the various functions which you will implement inside your constraint handler there exists a number
1476 * of <b> callback methods </b> associated with your constraint handler. Callback methods can be regarded as
1477 * tasks which your constraint handler is able to provide to the solver. They are grouped into two
1478 * categories:
1479 *
1480 * \ref CONS_FUNDAMENTALCALLBACKS "Fundamental Callback methods" are mandatory to implement
1481 * such that your code will work. For example, every constraint handler has to provide the
1482 * functionality to state whether all of its constraints are
1483 * fulfilled by a given variable assignment. Hence, the \ref CONSCHECK "CONSCHECK" callback is
1484 * one of the fundamental (or \a basic) callbacks of a constraint handler.
1485 *
1486 * Callbacks which are not necessarily implemented are grouped together as
1487 * \ref CONS_ADDITIONALCALLBACKS "additional callbacks". Such callbacks can be used to allocate and free memory
1488 * at different stages of the solving process. Although not mandatory, it might be useful to implement
1489 * some of these callbacks, e.g., to extend your constraint handler by a
1490 * \ref CONSSEPALP "separation" or \ref CONSPRESOL "presolving" functionality.
1491 *
1492 * All callbacks should be passed to SCIP during the SCIPinclude<PLUGINTYPE><PLUGINNAME> method
1493 * (e.g., SCIPincludeConshdlrKnapsack() for the \ref cons_knapsack.h "knapsack constraint handler").
1494 * Since SCIP version 3.0, two ways of setting callbacks can be used, either via SCIPincludeConshdlr()
1495 * (all at once, as it always was), or via SCIPincludeConshdlrBasic() and setter functions for additional callbacks.
1496 * Since the basic inclusion methods are very unlikely to change and will thus
1497 * make your code more stable towards future versions of SCIP with more callbacks,
1498 * we recommend the latter choice, as explained in the \ref CONS_INTERFACE "interface" section.
1499 *
1500 * @section CONS_FUNDAMENTALCALLBACKS Fundamental Callback Methods
1501 *
1502 * By implementing the fundamental callbacks, you define the semantics of the constraint class the constraint handler
1503 * deals with.
1504 * If these methods are implemented, the resulting code is already correct and finds the optimal solution to the
1505 * given problem instance.
1506 * However, it might be very slow because the additional features, like cut separation and domain propagation, are
1507 * missing.
1508 * In the C++ wrapper class scip::ObjConshdlr, the fundamental callback methods are virtual abstract member functions.
1509 * You have to implement them in order to be able to construct an object of your constraint handler class.
1510 *
1511 * There are three fundamental callback methods that are all dealing with the feasibility of a given solution.
1512 * They are called at different places in the algorithm and have slightly different meaning.
1513 * However, it is usually reasonable to implement a single local method that is called by all of the three callback
1514 * methods with slightly modified parameters.
1515 * The fourth method provides dual information that is used for example in preprocessing.
1516 *
1517 * Additional documentation for the callback methods can be found in type_cons.h.
1518 *
1519 * @subsection CONSCHECK
1520 *
1521 * The CONSCHECK callback gets a primal solution candidate in a SCIP_SOL* data structure
1522 * and has to check this solution for global feasibility.
1523 * It has to return a result SCIP_FEASIBLE, if the solution satisfies all the constraints of the constraint handler,
1524 * and a result SCIP_INFEASIBLE if there is at least one constraint that is violated.
1525 *
1526 * If the solution is not NULL, SCIP should also be informed about the constraint violation with a call to
1527 * SCIPupdateSolConsViolation() and additionally SCIPupdateSolLPRowViolation() for every row of the constraint's current
1528 * representation in the LP relaxation, if any such rows exist.
1529 * As a convenience method, SCIPupdateSolLPConsViolation() can be used if the constraint
1530 * is represented completely by a set of LP rows, meaning that the current constraint violation is equal to the maximum
1531 * of the contraint violations of the corresponding LP rows.
1532 *
1533 * The callback is used by primal heuristics to check a constructed solution for feasibility.
1534 * That means, the constraint handler has to deal with arbitrary solutions that do not necessarily satisfy the bounds
1535 * and constraints of the local subproblem.
1536 *
1537 * The value of a variable \em var in the given solution \em sol can be accessed by calling
1538 * \code
1539 * SCIPgetSolVal(scip, sol, var)
1540 * \endcode
1541 *
1542 * For example, the \ref cons_knapsack.h "knapsack constraint handler" loops over its constraints and
1543 * calculates the scalar product \f$w^T x\f$ of weights \f$w\f$ with the solution vector \f$x\f$.
1544 * This scalar product is compared with the capacity of the knapsack constraint.
1545 * If it exceeds the capacity, the CONSCHECK method is immediately aborted with the result SCIP_INFEASIBLE.
1546 * If all knapsack constraints are satisfied, a result SCIP_FEASIBLE is returned.
1547 *
1548 * @subsection CONSENFOLP
1549 *
1550 * The CONSENFOLP method is called after the price-and-cut loop was finished and an LP solution is available.
1551 * Like the CHECK call, the ENFOLP method should return a result SCIP_FEASIBLE, if the solution satisfies all the
1552 * constraints.
1553 * However, the behavior should be different, if the solution violates some of the associated constraints.
1554 * The constraint handler may return a result SCIP_INFEASIBLE in this situation, but this is not the best what
1555 * one can do.
1556 * The ENFOLP method has the possibility of \em resolving the infeasibility by
1557 * - stating that the current subproblem is infeasible (result SCIP_CUTOFF),
1558 * - adding an additional constraint that resolves the infeasibility (result SCIP_CONSADDED),
1559 * - reducing the domain of a variable (result SCIP_REDUCEDDOM),
1560 * - adding a cutting plane (result SCIP_SEPARATED),
1561 * - tightening the LP primal feasibility tolerance and requesting to solve the LP again (result SCIP_SOLVELP),
1562 * - performing a branching (result SCIP_BRANCHED).
1563 *
1564 * Note that in case SCIP_CONSADDED, the added constraints must be created with flag initial=TRUE.
1565 *
1566 * However, the solution is not given as a SCIP_SOL* data structure.
1567 *
1568 * The value of a variable <code>var</code> in the LP solution can be accessed by calling
1569 * \code
1570 * SCIPgetVarSol(scip, var)
1571 * \endcode
1572 * or by
1573 * \code
1574 * SCIPgetSolVal(scip, NULL, var)
1575 * \endcode
1576 * By using the latter method, you can have a single local method to check a solution for feasibility by passing
1577 * the given <code>sol</code> to the CONSCHECK call and by passing a NULL pointer as <code>sol</code> to
1578 * the CONSENFOLP and CONSENFOPS calls.
1579 *
1580 *
1581 * @subsection CONSENFOPS
1582 *
1583 * The CONSENFOPS callback is similar to the CONSENFOLP callback, but deals with \em pseudo \em solutions instead
1584 * of LP solutions.
1585 *
1586 * If the LP was not solved at the current subproblem (either because the user did not want to solve it, or because
1587 * numerical difficulties in the LP solving process were detected) no LP solution is available.
1588 * In this situation, the pseudo solution is used instead.
1589 * In this solution, the variables are set to the local bound which is best with respect to the objective function.
1590 * You can think of the pseudo solution as solution to the LP relaxation with all constraints except the bounds
1591 * being removed.
1592 *
1593 * Like the ENFOLP callback, the ENFOPS callback has to check whether the pseudo solution satisfies all the constraints
1594 * of the constraint handler.
1595 * The pseudo solution can be accessed by the same methods as the LP solution (SCIP knows, if the LP was solved at the
1596 * current subproblem, and returns either the LP solution or the pseudo solution).
1597 *
1598 * Unlike the ENFOLP callback, the ENFOPS callback must not add cuts and cannot return the result SCIP_SEPARATED.
1599 * It is, however, possible to force the solving of the LP by returning the result SCIP_SOLVELP.
1600 * For example, the infeasibility of a linear constraint that contains continuous variables cannot be resolved,
1601 * if all integer variables in the constraint are already fixed.
1602 * In this case, the LP has to be solved in order to get a solution that satisfies the linear constraint.
1603 *
1604 * @subsection CONSENFORELAX
1605 *
1606 * The CONSENFORELAX callback is similar to the CONSENFOLP and CONSENFOPS callbacks, but deals with relaxation solutions.
1607 *
1608 * If the best bound computed by a relaxator that includes the whole LP is strictly better than the bound of the LP itself,
1609 * the corresponding relaxation solution will get enforced. Therefore the CONSENFORELAX callback will only be called for
1610 * solutions that satisfy all active LP-constraints.
1611 *
1612 * Like the ENFOLP and ENFOPS callbacks, the ENFORELAX callback has to check whether the solution given in sol satisfies
1613 * all the constraints of the constraint handler. Since the callback is only called for relaxators including the whole LP,
1614 * cuts may be added with a result of SCIP_SEPARATED, like in the ENFOLP callback. It is also possible to return
1615 * SCIP_SOLVELP if the relaxation solution is invalid for some reason and the LP should be solved instead.
1616 *
1617 * Note that the CONSENFORELAX callback is only relevant if relaxators are used. Since the basic distribution of the
1618 * SCIP Optimization Suite does not contain any relaxators, this callback can be ignored unless any relaxators are added
1619 * via user-plugins.
1620 *
1621 * @subsection CONSLOCK
1622 *
1623 * The CONSLOCK callback provides dual information for a single constraint.
1624 * It has to tell SCIP, which variables are existing in the given constraint, and in which way modifications of these
1625 * variables may affect the feasibility of the constraint.
1626 *
1627 * For each variable that is affected by the constraint, the callback should call SCIPaddVarLocks():
1628 * - If the constraint may become violated by decreasing the value of a variable, it should call
1629 * SCIPaddVarLocks(scip, var, nlockspos, nlocksneg), saying that rounding down is potentially rendering the
1630 * (positive) constraint infeasible and rounding up is potentially rendering the negation of the constraint
1631 * infeasible.
1632 * - If the constraint may become violated by increasing the value of a variable, it should call
1633 * SCIPaddVarLocks(scip, var, nlocksneg, nlockspos), saying that rounding up is potentially rendering the
1634 * constraint's negation infeasible and rounding down is potentially rendering the constraint itself
1635 * infeasible.
1636 * - If the constraint may become violated by changing the variable in any direction, it should call
1637 * SCIPaddVarLocks(scip, var, nlockspos + nlocksneg, nlockspos + nlocksneg).
1638 *
1639 * <b>Note:</b> You do not have to worry about nlockspos and nlocksneg. These integer values are given as
1640 * parameter of the CONSLOCK callback (see type_cons.h). Just use these variables in the above described
1641 * fashion <b>without</b> adding or subtracting anything to them. In case of the knapsack constraints this
1642 * method looks like this.
1643 *
1644 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsLockKnapsack}
1645 *
1646 * To give same more intuition, consider the linear constraint \f$3x -5y +2z \leq 7\f$ as an example.
1647 * The CONSLOCK callback method of the linear constraint handler should call
1648 * SCIPaddVarLocks(scip, x, nlocksneg, nlockspos), SCIPaddVarLocks(scip, y, nlockspos, nlocksneg),
1649 * and SCIPaddVarLocks(scip, z, nlocksneg, nlockspos) to tell SCIP, that rounding up of \f$x\f$
1650 * and \f$z\f$ and rounding down of \f$y\f$ can destroy the feasibility of the constraint, while rounding
1651 * down of \f$x\f$ and \f$z\f$ and rounding up of \f$y\f$ can destroy the feasibility of the
1652 * constraint's negation \f$3x -5y +2z > 7\f$.
1653 * \n
1654 * A linear constraint \f$2 \leq 3x -5y +2z \leq 7\f$ should call
1655 * SCIPaddVarLocks(scip, ..., nlockspos + nlocksneg, nlockspos + nlocksneg) on all variables,
1656 * since rounding in both directions of each variable can destroy both the feasibility of the
1657 * constraint and it's negation \f$3x -5y +2z < 2\f$ or \f$3x -5y +2z > 7\f$.
1658 *
1659 *
1660 * @section CONS_ADDITIONALCALLBACKS Additional Callback Methods
1661 *
1662 * The additional callback methods do not need to be implemented in every case, but provide useful functionality
1663 * for many applications. They can be added to your constraint handler via setter functions, see
1664 * \ref CONS_INTERFACE "here".
1665 *
1666 * @subsection CONSFREE
1667 *
1668 * If you are using constraint handler data, you have to implement this method in order to free the
1669 * constraint handler data. This can be done by the following procedure (which is taken from the
1670 * \ref cons_knapsack.h "knapsack constraint handler"):
1671 *
1672 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsFreeKnapsack}
1673 *
1674 * If you have allocated memory for fields in your constraint handler data, remember to free this memory
1675 * before freeing the constraint handler data itself.
1676 * If you are using the C++ wrapper class, this method is not available.
1677 * Instead, just use the destructor of your class to free the member variables of your class.
1678 *
1679 * @subsection CONSHDLRCOPY
1680 *
1681 * The CONSHDLRCOPY callback is executed when the SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
1682 * callback as <code>NULL</code> the user disables the inclusion of the specified constraint handler into all copied SCIP
1683 * instances. This may deteriorate the performance of primal heuristics solving sub-SCIPs, since these constitute only
1684 * relaxations of the original problem if constraint handlers are missing.
1685 *
1686 * A usual implementation just
1687 * calls the interface method which includes the constraint handler to the model. For example, this callback is
1688 * implemented for the \ref cons_knapsack.c "knapsack constraint handler" as follows:
1689 *
1690 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsCopyKnapsack}
1691 *
1692 * <b>Note:</b> If you implement this callback, take care when setting the valid pointer.
1693 *
1694 * A problem copy is called valid if it is valid in both the primal and the dual sense, i.e., if
1695 *
1696 * - it is a relaxation of the source problem
1697 * - it does not enlarge the feasible region.
1698 *
1699 * A constraint handler may choose to not copy a constraint and still declare the resulting copy as valid. It must ensure
1700 * the feasibility of any solution to the problem copy in the original (source) space.
1701 *
1702 * <b>Note:</b> If you implement this callback and the constraint handler needs constraints (see CONSHDLR_NEEDSCONS),
1703 * then you also need to implement the callback \ref CONSCOPY.
1704 *
1705 * @subsection CONSINIT
1706 *
1707 * The CONSINIT callback is executed after the problem is transformed.
1708 * The constraint handler may, e.g., use this call to replace the original variables in its constraints by transformed
1709 * variables, or to initialize its statistical constraint handler data.
1710 *
1711 * @subsection CONSEXIT
1712 *
1713 * The CONSEXIT callback is executed before the transformed problem is freed.
1714 * In this method, the constraint handler should free all resources that were allocated for the solving process.
1715 *
1716 * @subsection CONSINITPRE
1717 *
1718 * The CONSINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
1719 * The constraint handler may use this call to initialize its presolving data, or to modify its constraints
1720 * before the presolving process begins.
1721 * Necessary constraint modifications that have to be performed even if presolving is turned off should be done here
1722 * or in the presolving deinitialization call.
1723 *
1724 * @subsection CONSEXITPRE
1725 *
1726 * The CONSEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
1727 * The constraint handler may use this call e.g. to clean up its presolving data, or to finally modify its constraints
1728 * before the branch-and-bound process begins.
1729 * Necessary constraint modifications that have to be performed even if presolving is turned off should be done here
1730 * or in the presolving initialization call.
1731 * Besides necessary modifications and clean up, no time consuming operations should be done.
1732 *
1733 * @subsection CONSINITSOL
1734 *
1735 * The CONSINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
1736 * begin.
1737 * The constraint handler may use this call to initialize its branch-and-bound specific data.
1738 *
1739 * @subsection CONSEXITSOL
1740 *
1741 * The CONSEXITSOL callback is executed before the branch-and-bound process is freed.
1742 * The constraint handler should use this call to clean up its branch-and-bound data, in particular to release
1743 * all LP rows that it has created or captured.
1744 *
1745 * @subsection CONSDELETE
1746 *
1747 * The CONSDELETE callback is executed if a constraint should be freed.
1748 * You can think of it as the destructor of a single constraint.
1749 * In the callback, you have to free the given constraint data.
1750 * The CONSDELETE callback is therefore the counterpart of the SCIPcreateCons...() interface method and the CONSTRANS
1751 * method.
1752 *
1753 * @subsection CONSTRANS
1754 *
1755 * The CONSTRANS method is called for each constraint of the constraint handler, when the user starts the solving
1756 * process.
1757 * It has to copy the original constraint data of the constraint to the memory for the transformed problem.
1758 * You can think of it as a copy constructor for a single constraint.
1759 *
1760 * The original model is copied in order to protect it from transformations that are applied during the solving process,
1761 * in particular during preprocessing.
1762 * Preprocessing and solving always operates on the transformed problem.
1763 * If the solving process data are freed, the original data still exist and the user can, e.g., modify the problem and
1764 * restart the solving process.
1765 *
1766 * If you do not implement the CONSTRANS method, a transformed constraint is created with the same flags and the
1767 * same constraint data pointer.
1768 * That means, the transformed constraint points to the original constraint data.
1769 * This is okay, as long as the constraint data is not changed during the solving process.
1770 * If you want to implement preprocessing methods or other methods that modify the constraint data, you have to
1771 * implement the CONSTRANS method and create a copy of the constraint data.
1772 *
1773 * Here is an example, which is taken from the \ref cons_knapsack.h "knapsack constraint handler":
1774 *
1775 * @refsnippet{src/scip/cons_knapsack.c,SnippetConsTransKnapsack}
1776 *
1777 * @subsection CONSINITLP
1778 *
1779 * The CONSINITLP callback is executed before the first LP relaxation is solved.
1780 * It should add the LP relaxations of all "initial" constraints to the LP. The method should scan the constraints
1781 * array for constraints that are marked initial via calls to SCIPconsIsInitial() and put the LP relaxation
1782 * of all initial constraints to the LP with calls to SCIPaddCut().
1783 *
1784 * @subsection CONSSEPALP
1785 *
1786 * The CONSSEPALP callback is executed during the price-and-cut loop of the subproblem processing.
1787 * It should try to generate cutting planes for the constraints of the constraint handler in order to separate
1788 * the current LP solution.
1789 * The method is called in the LP solution loop, which means that a valid LP solution exists.
1790 *
1791 * Usually, a separation callback searches and produces cuts, that are added with a call to SCIPaddCut().
1792 * If the cut should be remembered in the global cut pool, it may also call SCIPaddPoolCut().
1793 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
1794 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
1795 * However, the callback may also produce domain reductions or add other constraints.
1796 *
1797 * The CONSSEPALP callback has the following options:
1798 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1799 * - adding an additional constraint (result SCIP_CONSADDED)
1800 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1801 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
1802 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
1803 * (result SCIP_DIDNOTFIND)
1804 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
1805 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
1806 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
1807 *
1808 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1809 * CONSHDLR_SEPAFREQ, CONSHDLR_SEPAPRIORITY, and CONSHDLR_DELAYSEPA, which influence the behaviour of SCIP
1810 * calling CONSSEPALP.
1811 *
1812 * @subsection CONSSEPASOL
1813 *
1814 * The CONSSEPASOL callback is executed during separation loop on arbitrary primal solutions.
1815 * It should try to generate cutting planes for the constraints of the constraint handler in order to separate
1816 * the given primal solution.
1817 * The method is not called in the LP solution loop, which means that there is no valid LP solution.
1818 *
1819 * Usually, a separation callback searches and produces cuts, that are added with a call to SCIPaddCut().
1820 * If the cut should be remembered in the global cut pool, it may also call SCIPaddPoolCut().
1821 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
1822 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
1823 * However, the callback may also produce domain reductions or add other constraints.
1824 *
1825 * The CONSSEPASOL callback has the following options:
1826 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1827 * - adding an additional constraint (result SCIP_CONSADDED)
1828 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1829 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
1830 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
1831 * (result SCIP_DIDNOTFIND)
1832 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
1833 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
1834 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
1835 *
1836 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1837 * CONSHDLR_SEPAFREQ, CONSHDLR_SEPAPRIORITY, and CONSHDLR_DELAYSEPA, which influence the behaviour of SCIP
1838 * calling CONSSEPASOL.
1839 *
1840 * @subsection CONSPROP
1841 *
1842 * The CONSPROP callback is called during the subproblem processing.
1843 * It should propagate the constraints, which means that it should infer reductions in the variables' local bounds
1844 * from the current local bounds.
1845 * This technique, which is the main workhorse of constraint programming, is called "node preprocessing" in the
1846 * Integer Programming community.
1847 *
1848 * The CONSPROP callback has the following options:
1849 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1850 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1851 * - stating that the propagator searched, but did not find domain reductions, cutting planes, or cut constraints
1852 * (result SCIP_DIDNOTFIND)
1853 * - stating that the propagator was skipped (result SCIP_DIDNOTRUN)
1854 * - stating that the propagator was skipped, but should be called again (result SCIP_DELAYED)
1855 *
1856 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1857 * CONSHDLR_PROPFREQ, CONSHDLR_DELAYPROP, and CONSHDLR_PROP_TIMING, which influence the behaviour of SCIP
1858 * calling CONSPROP.
1859 *
1860 * @subsection CONSRESPROP
1861 *
1862 * If the constraint handler should support \ref CONF "conflict analysis", it has to supply a CONSRESPROP method.
1863 * It also should call SCIPinferVarLbCons() or SCIPinferVarUbCons() in domain propagation instead of SCIPchgVarLb() or
1864 * SCIPchgVarUb() in order to deduce bound changes on variables.
1865 * In the SCIPinferVarLbCons() and SCIPinferVarUbCons() calls, the handler provides the constraint that deduced the
1866 * variable's bound change, and an integer value <code>inferinfo</code> that can be arbitrarily chosen.
1867 *
1868 * The propagation conflict resolving method CONSRESPROP must then be implemented to provide the "reasons" for the bound
1869 * changes, i.e., the bounds of variables at the time of the propagation, which forced the constraint to set the
1870 * conflict variable's bound to its current value. It can use the <code>inferinfo</code> tag to identify its own propagation rule
1871 * and thus identify the "reason" bounds. The bounds that form the reason of the assignment must then be provided by
1872 * calls to SCIPaddConflictLb() and SCIPaddConflictUb() in the propagation conflict resolving method.
1873 *
1874 * <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
1875 * need more information to efficiently infer the original propagation steps that lead to the conflict. This would,
1876 * however, require too much space. In the extreme, the original propagation steps have to be repeated.
1877 *
1878 * 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
1879 * 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
1880 * variables are 0.0). It uses <code>SCIPinferVarLbCons(scip, z, 1.0, c, 0)</code> to apply this assignment (an
1881 * inference information tag is not needed by the constraint handler and is set to 0). In the conflict analysis, the
1882 * constraint handler may be asked to resolve the lower bound change on \f$z\f$ with constraint \f$c\f$, that was
1883 * applied at a time given by a bound change index "bdchgidx". With a call to <code>SCIPvarGetLbAtIndex(z,
1884 * bdchgidx)</code>, the handler can find out, that the lower bound of variable \f$z\f$ was set to 1.0 at the given
1885 * point of time, and should call <code>SCIPaddConflictUb(scip, x, bdchgidx)</code> and <code>SCIPaddConflictUb(scip, y,
1886 * 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
1887 * the deduction of the lower bound of \f$z\f$.
1888 *
1889 * If conflict analysis should not be supported, the method has to set the result code to SCIP_DIDNOTFIND. Although
1890 * this is a viable approach to circumvent the implementation of the usually rather complex conflict resolving method, it
1891 * will make the conflict analysis less effective. We suggest to first omit the conflict resolving method and check how
1892 * effective the \ref CONSPROP "propagation method" is. If it produces a lot of propagations for your application, you definitely should
1893 * consider implementing the conflict resolving method.
1894 *
1895 * @subsection CONSPRESOL
1896 *
1897 * The CONSPRESOL callback is called during preprocessing.
1898 * It should try to tighten the domains of the variables, tighten the coefficients of the constraints of the constraint
1899 * handler, delete redundant constraints, aggregate and fix variables if possible, and upgrade constraints to more
1900 * specific types.
1901 *
1902 * If the CONSPRESOL callback applies changes to the constraint data, you also have to implement the \ref CONSTRANS callback
1903 * in order to copy the constraint data to the transformed problem space and protect the original problem from the
1904 * preprocessing changes.
1905 *
1906 * To inform SCIP that the presolving method found a reduction the result pointer has to be set in a proper way.
1907 * The following options are possible:
1908 *
1909 * - SCIP_UNBOUNDED : at least one variable is not bounded by any constraint in objective direction
1910 * - SCIP_CUTOFF : at least one constraint is infeasible in the variable's bounds
1911 * - SCIP_SUCCESS : the presolver found a reduction
1912 * - SCIP_DIDNOTFIND : the presolver searched, but did not find a presolving change
1913 * - SCIP_DIDNOTRUN : the presolver was skipped
1914 * - SCIP_DELAYED : the presolver was skipped, but should be called again
1915 *
1916 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1917 * CONSHDLR_PRESOLTIMING and CONSHDLR_MAXPREROUNDS, which influence the behaviour of SCIP
1918 * calling CONSPRESOL.
1919 *
1920 * @subsection CONSACTIVE
1921 *
1922 * The CONSACTIVE callback method is called each time a constraint of the constraint handler is activated.
1923 * For example, if a constraint is added locally to a subproblem, the CONSACTIVE callback is called whenever the
1924 * search enters the subtree where the constraint exists.
1925 *
1926 * @subsection CONSDEACTIVE
1927 *
1928 * The CONSDEACTIVE callback method is called each time a constraint of the constraint handler is deactivated.
1929 * For example, if a constraint is added locally to a subproblem, the CONSDEACTIVE callback is called whenever the
1930 * search leaves the subtree where the constraint exists.
1931 *
1932 * @subsection CONSENABLE
1933 *
1934 * The CONSENABLE callback method is called each time a constraint of the constraint handler is enabled.
1935 * Constraints might be active without being enabled. In this case, only the feasibility checks are executed,
1936 * but domain propagation and separation is skipped.
1937 *
1938 * @subsection CONSDISABLE
1939 *
1940 * The CONSDISABLE callback method is called each time a constraint of the constraint handler is disabled.
1941 *
1942 * @subsection CONSPRINT
1943 *
1944 * The CONSPRINT callback method is called, when the user asks SCIP to display the problem to the screen
1945 * or save the problem into a file. This is, however, only the case if the user requested the CIP format.
1946 * For more details about reading and writing with SCIP we refer to the \ref READER "file readers". In this
1947 * callback method the constraint handler should display the data of the constraint in an appropriate form.
1948 * The output format that is defined by the CONSPRINT callbacks is called CIP format.
1949 * In later versions of SCIP, the constraint handlers should also be able to parse (i.e., read) constraints
1950 * which are given in CIP format.
1951 *
1952 * @subsection CONSCOPY
1953 *
1954 * The CONSCOPY callback method is used whenever constraints should be copied from one SCIP instance into another SCIP
1955 * instance. This method comes with the necessary parameters to do so, most importantly with a mapping of the variables of the
1956 * source SCIP instance to the corresponding variables of the target SCIP instance, and a mapping for the constraints
1957 * in the same way. For a complete list of all arguments of this callback method see type_cons.h.
1958 *
1959 * To get the corresponding target variable of a given source variable, you can use the variable map directly:
1960 *
1961 * \code
1962 * targetvar = (SCIP_VAR*) SCIPhashmapGetImage(varmap, sourcevar);
1963 * \endcode
1964 *
1965 * We recommend, however, to use the method SCIPgetVarCopy() which gets besides others the variable map and the constraint map as input
1966 * and returns the requested target variable. The advantage of using SCIPgetVarCopy() is that in the case
1967 * the required variable does not yet exist, it is created and added to the copy automatically:
1968 *
1969 * \code
1970 * SCIP_CALL( SCIPgetVarCopy(sourcescip, scip, sourcevar, &targetvar, varmap, consmap, global) );
1971 * \endcode
1972 *
1973 * Finally, the result pointer <code>valid</code> has to be set to TRUE if (and only if!) the copy process was successful.
1974 *
1975 * <b>Note:</b> Be careful when setting the valid pointer.
1976 * A problem copy is called valid if it is valid in both the primal and the dual sense, i.e., if
1977 *
1978 * - it is a relaxation of the source problem
1979 * - it does not enlarge the feasible region.
1980 *
1981 * A constraint handler may choose to not copy a constraint and still declare the resulting copy as valid. Therefore, it must ensure
1982 * the feasibility of any solution to the problem copy in the original (source) space.
1983 *
1984 * For an example implementation we refer to cons_linear.h. Additional documentation and the complete list of all
1985 * parameters can be found in the file in type_cons.h.
1986 *
1987 * @subsection CONSPARSE
1988 *
1989 * This method is the counter part to CONSPRINT. The ideal idea is that a constraint handler is able to parse the output
1990 * which it generated via the CONSPRINT method and creates the corresponding constraint. If the parsing was successfully
1991 * the result pointer success should be set to TRUE. An example implementation can be found in the \ref cons_linear.h
1992 * "linear constraint handler".
1993 *
1994 * @subsection CONSDELVARS
1995 *
1996 * This method should iterate over the given constraints and delete all variables that were marked for deletion by SCIPdelVar().
1997 * Variable deletion is especially interesting for branch-cut-and-price applications. If your constraint handler allows
1998 * the addition of variables during the solving process (see "modifiable" attribute of constraints), then you might also want to
1999 * implement this callback. This would allow you to not only create variables during solving, but also remove them dynamically
2000 * from the problem to reduce memory consumption in case they are no longer necessary.
2001 * During presolving, SCIP may also find that some variables are not needed anymore and then try
2002 * to delete them. Thus, if you do not implement this callback, the constraint handler should capture its variables via
2003 * SCIPcaptureVar() to prevent SCIP from erroneously deleting them.
2004 *
2005 * Additional documentation and the complete list of all parameters can be found in the file type_cons.h.
2006 *
2007 * @subsection CONSGETVARS
2008 *
2009 * The CONSGETVARS callback of a constraint handler can be implemented to give access to the constraint variables
2010 * as array, independently from the internal data structure of the constraint. The buffer array
2011 * is already passed, together with its length. Consider implementing @ref CONSGETNVARS, too, to have
2012 * information about the number of variables in this constraint.
2013 *
2014 * @subsection CONSGETNVARS
2015 *
2016 * This callback can be implemented to return the number of variables involved into a particular constraint.
2017 * In order to have access to the variable pointers, consider implementing @ref CONSGETVARS.
2018 *
2019 * @refsnippet{src/scip/cons_linear.c,Callback for the number of variables}
2020 *
2021 * @subsection CONSGETDIVEBDCHGS
2022 *
2023 * This callback is used inside the various diving heuristics of SCIP and does not affect the normal branching
2024 * of the actual search.
2025 * The constraint handler can provide this callback to render a current working solution (even more) infeasible by
2026 * suggesting one or several variable bound changes.
2027 *
2028 * @section CONS_FURTHERINFO Further documentation
2029 *
2030 * Further documentation can be found in @ref type_cons.h for callback descriptions and a complete
2031 * list of all callback parameters, or in @ref scip.h
2032 * for globally available functions.
2033 */
2034
2035/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2036
2037/**@page PRICER How to add variable pricers
2038 *
2039 * A pricer performs the dynamic generation of new variables in a column generation algorithm.
2040 * It is an algorithmic representation of a (usually exponential) number of variables.
2041 * The \ref PRICERREDCOST and \ref PRICERFARKAS methods are called after each LP solve to generate additional
2042 * variables which may improve the objective value or decrease the LP infeasibility, respectively.
2043 * \n
2044 * A complete list of all pricers contained in this release can be found \ref PRICERS "here".
2045 *
2046 * If the pricer finds one or more variables with negative reduced costs or negative Farkas value, it should
2047 * call SCIPcreateVar() and SCIPaddPricedVar() to create and add the variable to the problem. Additionally,
2048 * the pricer has to add the variable to all constraints in which it appears. Therefore, a pricer needs to
2049 * know the constraints of the model and their meaning. Note that all constraints for which additional variables
2050 * are generated by a pricer have to be flagged as "modifiable" in the SCIPcreateCons() call.
2051 *
2052 * We now explain how users can add their own pricers.
2053 * For example, look into the variable pricer for the binpacking problem (examples/Binpacking/src/pricer_binpacking.c) of the
2054 * Binpacking example project.
2055 * The example is written in C. C++ users can easily adapt the code by using the scip::scip::ObjPricer wrapper base class and
2056 * implement the scip_...() virtual methods instead of the SCIP_DECL_PRICER... callback methods.
2057 *
2058 * Additional documentation for the callback methods of a pricer can be found in the file
2059 * type_pricer.h.
2060 *
2061 * Notice that if your pricer cannot cope with variable bounds other than 0 and infinity, you have to mark
2062 * all constraints containing priced variables as modifiable, and you may have to disable reduced cost
2063 * strengthening by setting propagating/rootredcost/freq to -1.
2064 *
2065 * Here is what you have to do to implement a pricer:
2066 * -# Copy the template files src/scip/pricer_xyz.c and src/scip/pricer_xyz.h into files "pricer_mypricer.c"
2067 * and "pricer_mypricer.h".
2068 * \n
2069 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2070 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2071 * -# Use `SCIPincludePricerMypricer()` in order to include the pricer into your SCIP instance,
2072 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2073 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2074 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypricer".
2075 * -# Adjust the properties of the pricer (see \ref PRICER_PROPERTIES).
2076 * -# Define the pricer data (see \ref PRICER_DATA). This is optional.
2077 * -# Implement the interface methods (see \ref PRICER_INTERFACE).
2078 * -# Implement the fundamental callback methods (see \ref PRICER_FUNDAMENTALCALLBACKS).
2079 * -# Implement the additional callback methods (see \ref PRICER_ADDITIONALCALLBACKS). This is optional.
2080 *
2081 *
2082 * @section PRICER_PROPERTIES Properties of a Pricer
2083 *
2084 * At the top of the new file "pricer_mypricer.c" you can find the pricer properties.
2085 * These are given as compiler defines.
2086 * In the C++ wrapper class, you have to provide the pricer properties by calling the constructor
2087 * of the abstract base class scip::ObjPricer from within your constructor.
2088 * The properties you have to set have the following meaning:
2089 *
2090 * \par PRICER_NAME: the name of the pricer.
2091 * This name is used in the interactive shell to address the pricer.
2092 * Additionally, if you are searching for a pricer with SCIPfindPricer(), this name is looked up.
2093 * Names have to be unique: no two pricers may have the same name.
2094 *
2095 * \par PRICER_DESC: the description of the pricer.
2096 * This string is printed as a description of the pricer in the interactive shell.
2097 *
2098 * \par PRICER_PRIORITY: the priority of the pricer.
2099 * In each pricing round during the price-and-cut loop of the subproblem processing, the included pricers are
2100 * called in a predefined order, which is given by the priorities of the pricers.
2101 * The higher the priority, the earlier the pricer is called.
2102 * Usually, you will have only one pricer in your application and the priority is therefore irrelevant.
2103 *
2104 * \par PRICER_DELAY: the default for whether the pricer should be delayed, if other variables with negative reduced
2105 * costs have already been found in the current pricing round.
2106 * Variables may be declared to be "removable" in the SCIPcreateVar() call. This means that SCIP may remove the variable
2107 * from the LP if it was inactive (i.e., sitting at zero) for a number of LP solves. Nevertheless, after the removal of the
2108 * column from the LP, the variable still exists, and SCIP can calculate reduced costs and add it to the LP again if
2109 * necessary.
2110 * \n
2111 * If the PRICER_DELAY flag is set to TRUE (which is the common setting), all those existing variables with negative reduced costs
2112 * are added to the LP, and the LP is resolved before the pricer is called. Thus, the pricer can assume that all existing variables
2113 * have non-negative reduced costs if the \ref PRICERREDCOST method is called or non-positive Farkas value if the \ref PRICERFARKAS
2114 * method is called.
2115 * \n
2116 * In some applications, this inner pricing loop on the already existing variables can significantly slow down the solving process,
2117 * since it may lead to the addition of only very few variables in each pricing round. If this is an issue in your application,
2118 * you should consider setting the PRICER_DELAY flag to FALSE. You must, however, be aware of the fact that there may be already
2119 * existing variables with negative reduced costs. For example, this may lead to the issue that your pricer generates the same
2120 * variable twice. In some models, this is not critical because an optimal solution would choose only one of the two identical
2121 * variables anyway, but for other models this can lead to wrong results because the duplication of a variable essentially doubles
2122 * the upper bound of the variable.
2123 *
2124 *
2125 * @section PRICER_DATA Pricer Data
2126 *
2127 * Below the header "Data structures" you can find a struct which is called "struct SCIP_PricerData".
2128 * In this data structure, you can store the data of your pricer. For example, it may be convenient to store pointers to the
2129 * constraints of the problem instance here, because the pricer has to add variables to those constraints.
2130 * If you are using C++, you can add pricer data, as usual, as object variables to your class.
2131 * \n
2132 * Defining pricer data is optional. You can leave the struct empty.
2133 *
2134 *
2135 * @section PRICER_INTERFACE Interface Methods
2136 *
2137 * At the bottom of "pricer_mypricer.c" you can find the interface method SCIPincludePricerMypricer(), which also appears in "pricer_mypricer.h".
2138 * 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
2139 * be generated by this pricer.
2140 *
2141 * This method only has to be adjusted slightly.
2142 * It is responsible for notifying SCIP of the presence of the pricer. For this, you can either call SCIPincludePricer(),
2143 * or SCIPincludePricerBasic() since SCIP version 3.0. In the latter variant, \ref PRICER_ADDITIONALCALLBACKS "additional callbacks"
2144 * must be added via setter functions as, e.g., SCIPsetPricerCopy(). We recommend this latter variant because
2145 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2146 * variant must be manually adjusted with every SCIP release containing new callbacks for pricers in order to compile.
2147 *
2148 *
2149 * In addition, the pricer has to be activated before the solution process starts, like it is done
2150 * in the pricer of the Coloring application (applications/Coloring/src/reader_col.c) by calling
2151 * \code
2152 * SCIP_CALL( SCIPactivatePricer(scip, SCIPfindPricer(scip, "coloring")) );
2153 * \endcode
2154 *
2155 * If you are using pricer data, you have to allocate the memory for the data at this point.
2156 * You can do this by calling:
2157 * \code
2158 * SCIP_CALL( SCIPallocBlockMemory(scip, &pricerdata) );
2159 * \endcode
2160 * You also have to initialize the fields in struct SCIP_PricerData afterwards.
2161 *
2162 * You may also add user parameters for your pricer, see the method SCIPincludePricerColoring() in the pricer of the Coloring application
2163 * for an example of how to add user parameters.
2164 *
2165 *
2166 * @section PRICER_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Pricer
2167 *
2168 * The fundamental callback methods have to be implemented in order to obtain an operational algorithm.
2169 * They are passed together with the pricer itself to SCIP using SCIPincludePricer() or SCIPincludePricerBasic(),
2170 * see @ref PRICER_INTERFACE.
2171 *
2172 * In the case of a pricer, there are two fundamental callback methods, namely the @ref PRICERREDCOST and the
2173 * @ref PRICERFARKAS callbacks, which both search for new variables and add them to the problem.
2174 * These methods have to be implemented for every pricer; the other callback methods are optional.
2175 * In the C++ wrapper class scip::ObjPricer, the scip_redcost() method (which corresponds to the PRICERREDCOST callback)
2176 * is a virtual abstract member function. You have to implement it in order to be able to construct an object of your
2177 * pricer class.
2178 *
2179 * Additional documentation for the callback methods can be found in type_pricer.h.
2180 *
2181 * @subsection PRICERREDCOST
2182 *
2183 * The PRICERREDCOST callback is called inside the price-and-cut loop of the subproblem solving process if the current LP relaxation
2184 * is feasible.
2185 * It should search for additional variables that can contribute to improve the current LP's solution value.
2186 * In standard branch-and-price, these are variables with negative dual feasibility, that is negative
2187 * reduced costs for non-negative variables, positive reduced costs for non-positive variables,
2188 * and non-zero reduced costs for variables that can be negative and positive.
2189 *
2190 * Whenever the pricer finds a variable with negative dual feasibility, it should call SCIPcreateVar()
2191 * and SCIPaddPricedVar() to add the variable to the problem. Furthermore, it should call the appropriate
2192 * methods of the constraint handlers to add the necessary variable entries to the constraints, see pub_cons.h.
2193 *
2194 * In the usual case that the pricer either adds a new variable or ensures that there are no further variables with negative dual feasibility,
2195 * the result pointer should be set to SCIP_SUCCESS. Only if the pricer aborts pricing without creating a new variable, but
2196 * there might exist additional variables with negative dual feasibility, the result pointer should be set to SCIP_DIDNOTRUN.
2197 * In this case, which sometimes is referred to as "early branching", the LP solution will not be used as a lower bound.
2198 * The pricer can, however, store a valid lower bound in the <code>lowerbound</code> pointer.
2199 *
2200 * Pricers usually need the dual LP solution as input for the pricing algorithm.
2201 * Since SCIP does not know the semantics of the individual constraints in the problem, the dual solution
2202 * has to be provided by the constraint handlers.
2203 * For example, the \ref cons_setppc.h "setppc constraint handler", which deals with set partitioning, packing, and covering constraints, provides
2204 * the method SCIPgetDualsolSetppc() to access the dual solution value for a single constraint.
2205 * Similarly, the dual solution of a linear constraint can be queried with the method SCIPgetDualsolLinear() of cons_linear.h.
2206 * The reduced costs of the existing variables can be accessed with the method SCIPgetVarRedcost().
2207 *
2208 * @subsection PRICERFARKAS
2209 *
2210 * If the current LP relaxation is infeasible, it is the task of the pricer to generate additional variables that can
2211 * potentially render the LP feasible again. In standard branch-and-price, these are variables with positive Farkas values,
2212 * and the PRICERFARKAS method should identify those variables.
2213 *
2214 * If the LP was proven to be infeasible, we have an infeasibility proof by the dual Farkas multipliers \f$y\f$.
2215 * 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
2216 * by the sides of the LP rows and the sign of \f$y\f$:
2217 * - if \f$y_i\f$ is positive, \f$b_i\f$ is the left hand side of the row,
2218 * - if \f$y_i\f$ is negative, \f$b_i\f$ is the right hand side of the row.
2219 *
2220 * \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$,
2221 * especially by the (for this inequality least infeasible solution) \f$x'\f$ defined by
2222 * - \f$x'_i := ub_i\f$, if \f$y^T A_i \ge 0\f$
2223 * - \f$x'_i := lb_i\f$, if \f$y^T A_i < 0\f$.
2224 * 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$.
2225 *
2226 * To apply Farkas pricing, the pricer needs to know the Farkas values of the constraints. Like the dual solution values for
2227 * feasible LP solutions, the dual Farkas values for infeasible solutions can be obtained by constraint handler interface
2228 * methods such as the SCIPgetDualfarkasLinear() method of the linear constraint handler.
2229 * The Farkas values for the bounds of the variables can be accessed with SCIPgetVarFarkasCoef().
2230 *
2231 * It is useful to note that Farkas pricing is the same as the regular pricing with a zero objective function.
2232 * Therefore, a typical implementation of a pricer would consist of a generic pricing algorithm that gets a dual solution and an
2233 * objective function vector as input and generates variables by calling SCIPcreateVar() and SCIPaddPricedVar().
2234 * The PRICERREDCOST callback would call this function with the regular objective function and the regular dual solution vector,
2235 * while the PRICERFARKAS callback would call this function with a zero objective function and the Farkas vector.
2236 * From a practical point of view, it is usually the simplest approach to provide just one Boolean flag to the generic pricing
2237 * algorithm in order to identify whether it is reduced cost or Farkas pricing. Then, the algorithm would just call the appropriate
2238 * methods to access the dual solution or objective function, depending on the Boolean flag.
2239 *
2240 * @section PRICER_ADDITIONALCALLBACKS Additional Callback Methods of a Pricer
2241 *
2242 * The additional callback methods do not need to be implemented in every case.
2243 * However, some of them have to be implemented for most applications. They can either be passed directly with
2244 * SCIPincludePricer() to SCIP or via specific <b>setter functions</b> after a call of SCIPincludePricerBasic(),
2245 * see also @ref PRICER_INTERFACE.
2246 *
2247 * @subsection PRICERFREE
2248 *
2249 * If you are using pricer data, you have to implement this method in order to free the pricer data.
2250 * This can be done by the procedure described in stp/src/pricer_stp.c,
2251 * see https://scipjack.zib.de/.
2252 *
2253 * If you have allocated memory for fields in your pricer data, remember to free this memory
2254 * before freeing the pricer data itself.
2255 * If you are using the C++ wrapper class, this method is not available.
2256 * Instead, just use the destructor of your class to free the member variables of your class.
2257 *
2258 * @subsection PRICERCOPY
2259 *
2260 * The PRICERCOPY callback is executed when the SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
2261 * callback as <code>NULL</code> the user disables the inclusion of the pricer into all copied SCIP
2262 * instances. This means that primal heuristics will work on a sub-SCIP that contains only a part of the variables
2263 * and no variables are priced in during the solving process of the sub-SCIP. Therefore, primal solutions found in the
2264 * copied problem are typically still valid for the original problem and used for its solving process,
2265 * but dual reductions cannot be transferred to the original problem.
2266 *
2267 * <b>Note:</b> If you implement this callback, be careful when setting the valid pointer. The valid pointer should be
2268 * set to TRUE if (and only if!) you can make sure that all necessary data of the pricer are copied
2269 * correctly. If the complete problem is validly copied, i.e. if the copy methods of all problem defining plugins
2270 * (constraint handlers and pricers) return <code>*valid = TRUE</code>, then dual reductions found for the copied problem can be
2271 * transferred to the original SCIP instance. Thus, if the valid pointer is wrongly set to TRUE, it might happen that
2272 * optimal solutions are cut off.
2273 *
2274 * @subsection PRICERINIT
2275 *
2276 * The PRICERINIT callback is executed after the problem is transformed.
2277 * The pricer may, e.g., use this call to replace the original constraints stored in its pricer data by transformed
2278 * constraints, or to initialize other elements of its pricer data.
2279 *
2280 * @subsection PRICEREXIT
2281 *
2282 * The PRICEREXIT callback is executed before the transformed problem is freed.
2283 * In this method, the pricer should free all resources that have been allocated for the solving process in PRICERINIT.
2284 *
2285 * @subsection PRICERINITSOL
2286 *
2287 * The PRICERINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to begin.
2288 * The pricer may use this call to initialize its branch-and-bound specific data.
2289 *
2290 * @subsection PRICEREXITSOL
2291 *
2292 * The PRICEREXITSOL callback is executed before the branch-and-bound process is freed.
2293 * The pricer should use this call to clean up its branch-and-bound data, which was allocated in PRICERINITSOL.
2294 *
2295 * @section PRICER_REMARKS Further remarks
2296 *
2297 * 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".
2298 * Otherwise, SCIP will use its default branching rules, if necessary (which all branch on variables). This
2299 * could disturb the pricing problem or branching might not even be possible, e.g., if all variables created thus far have already been fixed.
2300 *
2301 * Note that if the original problem is a maximization problem, SCIP will transform the problem into a minimization
2302 * problem by multiplying the objective function by -1. The pricer has to take care of this by multiplying
2303 * the original objective function value of all variables created during the solving process by -1.
2304 *
2305 * In some cases, bounds on variables are implicitly enforced by constraints of the problem and the objective function.
2306 * 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
2307 * care about the corresponding dual values.
2308 * We call these bounds lazy bounds, they may be set by SCIPchgVarLbLazy() and SCIPchgVarUbLazy() for upper or lower bounds, respectively.
2309 * If the lazy bound equals the local bound, the corresponding bound is not put into the LP.
2310 * In diving mode, lazy bounds are explicitly put into the LP, because changing the objective (which is only possible in diving)
2311 * might reverse the implicitly given bounds. When diving is finished, the bounds are again removed from the LP.
2312 */
2313
2314/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2315
2316/**@page PRESOL How to add presolvers
2317 *
2318 * Presolvers are used to reduce the size of the model by removing irrelevant information like redundant constraints,
2319 * to strengthen the LP relaxation by exploiting integrality information, and to extract useful information in the
2320 * presolving step.
2321 * Constraint based presolving is done in the CONSPRESOL callback methods of the constraint handlers, see \ref CONSPRESOL.
2322 * Some propagation steps can already be applied in presolving via the PROPRESOL callback methods of propagators, see \ref PROPPRESOL.
2323 * The presolver plugins complement these by additional, usually optimality based, presolving reductions.
2324 * \n
2325 * A complete list of all presolvers contained in this release can be found \ref PRESOLVERS "here".
2326 *
2327 * We now explain how users can add their own presolvers.
2328 * Take the trivial presolver (src/scip/presol_trivial.c) as an example.
2329 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjPresol wrapper
2330 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_PRESOL... callback methods.
2331 *
2332 * Additional documentation for the callback methods of a presolver, in particular for their input parameters,
2333 * can be found in the file type_presol.h.
2334 *
2335 * Here is what you have to do to implement a presolver:
2336 * -# Copy the template files src/scip/presol_xyz.c and src/scip/presol_xyz.h into files named "presol_mypresolver.c"
2337 * and "presol_mypresolver.h".
2338 * \n
2339 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2340 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2341 * -# Use `SCIPincludePresolMypresolver()` in order to include the presolver into your SCIP instance,
2342 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2343 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2344 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypresolver".
2345 * -# Adjust the properties of the presolver (see \ref PRESOL_PROPERTIES).
2346 * -# Define the presolver data (see \ref PRESOL_DATA). This is optional.
2347 * -# Implement the interface methods (see \ref PRESOL_INTERFACE).
2348 * -# Implement the fundamental callback methods (see \ref PRESOL_FUNDAMENTALCALLBACKS).
2349 * -# Implement the additional callback methods (see \ref PRESOL_ADDITIONALCALLBACKS). This is optional.
2350 *
2351 *
2352 * @section PRESOL_PROPERTIES Properties of a Presolver
2353 *
2354 * At the top of the new file "presol_mypresolver.c", you can find the presolver properties.
2355 * These are given as compiler defines.
2356 * In the C++ wrapper class, you have to provide the presolver properties by calling the constructor
2357 * of the abstract base class scip::ObjPresol from within your constructor.
2358 * The properties you have to set have the following meaning:
2359 *
2360 * \par PRESOL_NAME: the name of the presolver.
2361 * This name is used in the interactive shell to address the presolver.
2362 * Additionally, if you are searching for a presolver with SCIPfindPresol(), this name is looked up.
2363 * Names have to be <b>unique</b>: no two presolvers may have the same name.
2364 *
2365 * \par PRESOL_DESC: the description of the presolver.
2366 * This string is printed as a description of the presolver in the interactive shell.
2367 *
2368 * \par PRESOL_TIMING: the default timing of the presolver.
2369 * There are three presolving timings: FAST, MEDIUM, and EXHAUSTIVE.
2370 * Every presolving round starts with the FAST presolvers. MEDIUM presolvers are only called, if FAST presolvers did not find
2371 * enough reductions in this round so far, and EXHAUSTIVE presolving steps are only performed if all presolvers called before
2372 * in this round were unsuccessful.
2373 * Presolvers should be assigned a timing based on how expensive they are, e.g., presolvers that provide fast algorithms that
2374 * usually have a high impact (i.e., remove lots of variables or tighten bounds of many variables) should have a timing FAST.
2375 * If a presolver implements different algorithms of different complexity, it may also get multiple timings and check the timing
2376 * internally in the \ref PRESOLEXEC callback to decide which algorithms to run.
2377 *
2378 * \par PRESOL_PRIORITY: the priority of the presolver.
2379 * Within a presolving round, when calling all presolvers and presolving methods of propagators and constraint handlers
2380 * with a given timing, those are called in
2381 * a predefined order, which is given by the priorities of the presolvers and the check priorities of the
2382 * constraint handlers, see \ref CONS_PROPERTIES.
2383 * First, the presolvers with non-negative priority are called in the order of decreasing priority.
2384 * Next, the presolving methods of the different constraint handlers are called in the order of decreasing check
2385 * priority.
2386 * Finally, the presolvers with negative priority are called in the order of decreasing priority.
2387 * \n
2388 * Again, presolvers that provide fast algorithms that usually have a high impact (i.e., remove lots of variables or tighten
2389 * bounds of many variables) should have a high priority.
2390 * An easy way to list the timings and
2391 * priorities of all presolvers, propagators, and constraint handlers is to type "display presolvers", "display propagators",
2392 * and "display conshdlrs" in the interactive shell of SCIP.
2393 *
2394 * \par PRESOL_MAXROUNDS: the default maximal number of rounds the presolver participates in.
2395 * The presolving is conducted in rounds: the presolvers and presolving methods of the constraint handlers
2396 * are called iteratively until no more reductions have been found or some other abort criterion applies.
2397 * The "maxrounds" parameter of a presolver imposes a limit on the number of presolving rounds in which the
2398 * presolver is called. The PRESOL_MAXROUNDS property specifies the default value for this parameter.
2399 * A value of -1 represents an unlimited number of rounds.
2400 *
2401 *
2402 * @section PRESOL_DATA Presolver Data
2403 *
2404 * Below the header "Data structures" you can find a struct which is called "struct SCIP_PresolData".
2405 * In this data structure, you can store the data of your presolver. For example, you should store the adjustable parameters
2406 * of the presolver in this data structure.
2407 * If you are using C++, you can add presolver data as usual as object variables to your class.
2408 * \n
2409 * Defining presolver data is optional. You can leave this struct empty.
2410 *
2411 *
2412 * @section PRESOL_INTERFACE Interface Methods
2413 *
2414 * At the bottom of "presol_mypresolver.c", you can find the interface method SCIPincludePresolMypresolver(),
2415 * which also appears in "presol_mypresolver.h"
2416 * SCIPincludePresolMypresolver() is called by the user, if (s)he wants to include the presolver,
2417 * i.e., if (s)he wants to use the presolver in his/her application.
2418 *
2419 * This method only has to be adjusted slightly.
2420 * It is responsible for notifying SCIP of the presence of the presolver. For this, you can either call SCIPincludePresol(),
2421 * or SCIPincludePresolBasic() since SCIP version 3.0. In the latter variant, \ref PRESOL_ADDITIONALCALLBACKS "additional callbacks"
2422 * must be added via setter functions as, e.g., SCIPsetPresolCopy(). We recommend this latter variant because
2423 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2424 * variant must be manually adjusted with every SCIP release containing new callbacks for presolvers in order to compile.
2425 *
2426 * If you are using presolver data, you have to allocate the memory for the data at this point.
2427 * You can do this by calling:
2428 * \code
2429 * SCIP_CALL( SCIPallocBlockMemory(scip, &presoldata) );
2430 * \endcode
2431 * You also have to initialize the fields in struct SCIP_PresolData afterwards. For freeing the
2432 * presolver data, see \ref PRESOLFREE.
2433 *
2434 * You may also add user parameters for your presolver, see \ref PARAM for how to add user parameters and
2435 * the method SCIPincludePresolTrivial() in src/scip/presol_trivial.c for an example.
2436 *
2437 *
2438 * @section PRESOL_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Presolver
2439 *
2440 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2441 * an operational algorithm.
2442 * They are passed together with the presolver itself to SCIP using SCIPincludePresol() or SCIPincludePresolBasic(),
2443 * see @ref PRESOL_INTERFACE.
2444 *
2445 * Presolver plugins have only one fundamental callback method, namely the @ref PRESOLEXEC method.
2446 * This method has to be implemented for every presolver; the other callback methods are optional.
2447 * In the C++ wrapper class scip::ObjPresol, the scip_exec() method (which corresponds to the PRESOLEXEC callback) is a virtual
2448 * abstract member function.
2449 * You have to implement it in order to be able to construct an object of your presolver class.
2450 *
2451 * Additional documentation for the callback methods, in particular to their input parameters,
2452 * can be found in type_presol.h.
2453 *
2454 * @subsection PRESOLEXEC
2455 *
2456 * The PRESOLEXEC callback is called inside the presolving loop and should perform the actual presolving reductions.
2457 * It should inspect the problem instance at hand and simplify it by tightening bounds of variables, aggregating or fixing
2458 * variables, changing the type of variables, modifying the graph that represents the instance of your application, and
2459 * the like.
2460 *
2461 * Typical methods called by a presolver are, for example, SCIPchgVarType(), SCIPfixVar(), SCIPaggregateVars(), SCIPtightenVarLb(),
2462 * and SCIPtightenVarUb().
2463 *
2464 *
2465 * @section PRESOL_ADDITIONALCALLBACKS Additional Callback Methods of a Presolver
2466 *
2467 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2468 * implemented for most applications, they can be used, for example, to initialize and free private data.
2469 * Additional callbacks can either be passed directly with SCIPincludePresol() to SCIP or via specific
2470 * <b>setter functions</b> after a call of SCIPincludePresolBasic(), see also @ref PRESOL_INTERFACE.
2471 *
2472 * @subsection PRESOLFREE
2473 *
2474 * 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.
2475 * This can be done by the following procedure:
2476 *
2477 * @refsnippet{src/scip/presol_boundshift.c,SnippetPresolFreeBoundshift}
2478 *
2479 * If you have allocated memory for fields in your presolver data, remember to free this memory
2480 * before freeing the presolver data itself.
2481 * If you are using the C++ wrapper class, this method is not available.
2482 * Instead, just use the destructor of your class to free the member variables of your class.
2483 *
2484 * @subsection PRESOLINIT
2485 *
2486 * The PRESOLINIT callback is executed after the problem is transformed.
2487 * The presolver may, e.g., use this call to initialize its presolver data.
2488 * The difference between the original and the transformed problem is explained in
2489 * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
2490 *
2491 * @subsection PRESOLCOPY
2492 *
2493 * The PRESOLCOPY callback is executed when a SCIP instance is copied, e.g. to
2494 * solve a sub-SCIP. By
2495 * defining this callback as
2496 * <code>NULL</code> the user disables the execution of the specified
2497 * presolver for all copied SCIP instances. This may deteriorate the performance
2498 * of primal heuristics using sub-SCIPs.
2499 *
2500 * @subsection PRESOLEXIT
2501 *
2502 * The PRESOLEXIT callback is executed before the transformed problem is freed.
2503 * In this method, the presolver should free all resources that have been allocated for the solving process in PRESOLINIT.
2504 *
2505 * @subsection PRESOLINITPRE
2506 *
2507 * The PRESOLINITPRE callback is executed when the presolving is about to begin.
2508 * The presolver may use this call to initialize its presolving data which only need to exist during the presolving stage.
2509 *
2510 * @subsection PRESOLEXITPRE
2511 *
2512 * The PRESOLEXITPRE callback is executed after presolving finishes and before the branch-and-bound process begins.
2513 * The presolver should use this call to clean up its presolving data, which was allocated in PRESOLINITPRE.
2514 */
2515
2516/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2517
2518/**@page SEPA How to add separators
2519 *
2520 * Separators are used to generate cutting planes that strengthen the LP relaxation of the problem formulation, but are
2521 * not required for a completeness and correctness of the model.
2522 * In contrast, constraint-based cutting planes, the second type of cutting planes in SCIP, are separated in the CONSSEPALP and
2523 * CONSSEPASOL callback methods of the constraint handlers, see \ref CONSSEPALP and \ref CONSSEPASOL. These cuts are
2524 * valid inequalities or even facets of the polyhedron described by a single constraint or a subset of the constraints of
2525 * a single constraint class. See also
2526 * "When should I implement a constraint handler, when should I implement a separator?" on \ref FAQ.
2527 * \n
2528 * A complete list of all separators contained in this release can be found \ref SEPARATORS "here".
2529 *
2530 * We now explain how users can add their own separators.
2531 * Take the separator for the class of Gomory mixed integer inequalities (src/scip/sepa_gomory.c) as an example.
2532 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjSepa wrapper
2533 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_SEPA... callback methods.
2534 *
2535 * Additional documentation for the callback methods of a separator, in particular for the input parameters,
2536 * can be found in the file type_sepa.h.
2537 *
2538 * Here is what you have to do to implement a separator:
2539 * -# Copy the template files src/scip/sepa_xyz.c and src/scip/sepa_xyz.h into files "sepa_myseparator.c"
2540 * and "sepa_myseparator.h".
2541 \n
2542 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2543 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2544 * -# Use `SCIPincludeSepaMyseparator()` in order to include the separator into your SCIP instance,
2545 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2546 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2547 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myseparator".
2548 * -# Adjust the properties of the separator (see \ref SEPA_PROPERTIES).
2549 * -# Define the separator data (see \ref SEPA_DATA). This is optional.
2550 * -# Implement the interface methods (see \ref SEPA_INTERFACE).
2551 * -# Implement the fundamental callback methods (see \ref SEPA_FUNDAMENTALCALLBACKS).
2552 * -# Implement the additional callback methods (see \ref SEPA_ADDITIONALCALLBACKS). This is optional.
2553 *
2554 *
2555 * @section SEPA_PROPERTIES Properties of a Separator
2556 *
2557 * At the top of the new file "sepa_myseparator.c", you can find the separator properties.
2558 * These are given as compiler defines.
2559 * In the C++ wrapper class, you have to provide the separator properties by calling the constructor
2560 * of the abstract base class scip::ObjSepa from within your constructor.
2561 * The properties you have to set have the following meaning:
2562 *
2563 * \par SEPA_NAME: the name of the separator.
2564 * This name is used in the interactive shell to address the separator.
2565 * Additionally, if you are searching for a separator with SCIPfindSepa(), this name is looked up.
2566 * Names have to be unique: no two separators may have the same name.
2567 *
2568 * \par SEPA_DESC: the description of the separator.
2569 * This string is printed as a description of the separator in the interactive shell.
2570 *
2571 * \par SEPA_PRIORITY: the priority of the separator.
2572 * In each separation round during the price-and-cut loop of the subproblem processing or the separation loop
2573 * of the primal solution separation, the separators and separation methods of the constraint handlers are called in
2574 * a predefined order, which is given by the priorities of the separators and the separation priorities
2575 * of the constraint handlers (see \ref CONS_PROPERTIES).
2576 * First, the separators with non-negative priority are called in the order of decreasing priority.
2577 * Next, the separation methods of the constraint handlers are called in the order of decreasing separation
2578 * priority.
2579 * Finally, the separators with negative priority are called in the order of decreasing priority. An easy way to list the
2580 * priorities of all separators and constraint handlers is to type "display separators" and "display conshdlrs" in
2581 * the interactive shell.
2582 * \n
2583 * The priority of the separator should be set according to the complexity of the cut separation algorithm and the
2584 * impact of the resulting cuts: separators that provide fast algorithms that usually have a high impact (i.e., cut off
2585 * a large portion of the LP relaxation) should have a high priority.
2586 * See \ref SEPAEXECLP and \ref SEPAEXECSOL for further details of the separation callbacks.
2587 *
2588 * \par SEPA_FREQ: the default frequency for separating cuts.
2589 * The frequency defines the depth levels at which the separation methods \ref SEPAEXECLP and \ref SEPAEXECSOL are called.
2590 * For example, a frequency of 7 means, that the separation callback is executed for subproblems that are in depth
2591 * 0, 7, 14, ... of the branching tree. A frequency of 0 means, that the separation method is only called at the root node.
2592 * A frequency of -1 disables the separator.
2593 * \n
2594 * The frequency can be adjusted by the user. This property of the separator only defines the default value of the frequency.
2595 * If you want to have a more flexible control of when to execute the separation algorithm, you have to assign
2596 * a frequency of 1 and implement a check at the beginning of your separation methods whether you really want to execute
2597 * the separation or not. If you do not want to execute it, set the result code of
2598 * \ref SEPAEXECLP and \ref SEPAEXECSOL to SCIP_DIDNOTRUN.
2599 *
2600 * \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.
2601 * At the current branch-and-bound node, the relative distance from its dual bound (local dual bound)
2602 * to the primal bound compared to the best node's dual bound (global dual bound) is considered. The separation method
2603 * of the separator will only be applied at the current node if this relative distance does not exceed SEPA_MAXBOUNDDIST.
2604 * \n
2605 * For example, if the global dual bound is 50 and the primal bound is 60, SEPA_MAXBOUNDDIST = 0.25 means that separation
2606 * 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
2607 * than or equal to 52.5.
2608 * \n
2609 * In particular, the values 0.0 and 1.0 mean that separation is applied at the current best node only or at all
2610 * nodes, respectively. Since separation seems to be most important to apply at nodes that define to the global
2611 * dual bound, 0.0 is probably a good choice for SEPA_MAXBOUNDDIST.
2612 * Note that separators with a frequency of SEPA_FREQ = 0 are only applied at the root node.
2613 * Obviously, at the root node the local dual bound is equal to the global dual bound and thus, the separator is called
2614 * for any value of SEPA_MAXBOUNDDIST.
2615 *
2616 * \par SEPA_USESSUBSCIP: Does the separator use a secondary SCIP instance?
2617 * Some heuristics and separators solve MIPs or SAT problems and use a secondary SCIP instance. Examples are
2618 * Large Neighborhood Search heuristics such as RINS and Local Branching or the CGMIP separator. To avoid recursion,
2619 * these plugins usually deactivate all other plugins that solve MIPs. If a separator uses a secondary SCIP instance,
2620 * this parameter has to be TRUE and it is recommended to call SCIPsetSubscipsOff() for the secondary SCIP instance.
2621 *
2622 * \par SEPA_DELAY: the default for whether the separation method should be delayed, if other separators or constraint handlers found cuts.
2623 * If the separator's separation method is marked to be delayed, it is only executed after no other separator
2624 * or constraint handler found a cut during the price-and-cut loop, and in the last separation or stalling round,
2625 * either in the end, or in an additional round if only the maximal subsequent round is exceeded.
2626 * If the separation method of the separator is very expensive, you may want to mark it to be delayed until all cheap
2627 * separation methods have been executed.
2628 *
2629 * @section SEPA_DATA Separator Data
2630 *
2631 * Below the header "Data structures" you can find a struct which is called "struct SCIP_SepaData".
2632 * In this data structure, you can store the data of your separator. For example, you should store the adjustable
2633 * parameters of the separator in this data structure. In a separator, user parameters for the maximal number of
2634 * separation rounds per node and for the maximal number of cuts separated per separation round might be useful.
2635 * If you are using C++, you can add separator data as usual as object variables to your class.
2636 * \n
2637 * Defining separator data is optional. You can leave the struct empty.
2638 *
2639 * @section SEPA_INTERFACE Interface Methods
2640 *
2641 * At the bottom of "sepa_myseparator.c", you can find the interface method SCIPincludeSepaMyseparator(),
2642 * which also appears in "sepa_myseparator.h"
2643 * SCIPincludeSepaMyseparator() is called by the user, if (s)he wants to include the separator,
2644 * i.e., if (s)he wants to use the separator in his/her application.
2645 *
2646 * This method only has to be adjusted slightly.
2647 * It is responsible for notifying SCIP of the presence of the separator. For this, you can either call SCIPincludeSepa(),
2648 * or SCIPincludeSepaBasic() since SCIP version 3.0. In the latter variant, \ref SEPA_ADDITIONALCALLBACKS "additional callbacks"
2649 * must be added via setter functions as, e.g., SCIPsetSepaCopy(). We recommend this latter variant because
2650 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2651 * variant must be manually adjusted with every SCIP release containing new callbacks for separators in order to compile.
2652 *
2653 * If you are using separator data, you have to allocate the memory
2654 * for the data at this point. You can do this by calling:
2655 * \code
2656 * SCIP_CALL( SCIPallocBlockMemory(scip, &sepadata) );
2657 * \endcode
2658 * You also have to initialize the fields in "struct SCIP_SepaData" afterwards. For freeing the
2659 * separator data, see \ref SEPAFREE.
2660 *
2661 * You may also add user parameters for your separator, see \ref PARAM for how to add user parameters and
2662 * the method SCIPincludeSepaGomory() in src/scip/sepa_gomory.c for an example.
2663 *
2664 *
2665 * @section SEPA_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Separator
2666 *
2667 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2668 * an operational algorithm.
2669 * They are passed together with the separator itself to SCIP using SCIPincludeSepa() or SCIPincludeSepaBasic(),
2670 * see @ref SEPA_INTERFACE.
2671 *
2672 * Separator plugins have two callbacks, @ref SEPAEXECLP and @ref SEPAEXECSOL, of which at least one must be implemented.
2673 *
2674 * Additional documentation for the callback methods, in particular to their input parameters,
2675 * can be found in type_sepa.h.
2676 *
2677 * @subsection SEPAEXECLP
2678 *
2679 * The SEPAEXECLP callback is executed during the price-and-cut loop of the subproblem processing.
2680 * It should try to generate general purpose cutting planes in order to separate the current LP solution.
2681 * The method is called in the LP solution loop, which means that a valid LP solution exists.
2682 *
2683 * Usually, the callback searches and produces cuts, that are added with a call to SCIPaddCut().
2684 * If the cut should be added to the global cut pool, it calls SCIPaddPoolCut().
2685 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
2686 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
2687 * In addition to LP rows, the callback may also produce domain reductions or add additional constraints.
2688 *
2689 * Overall, the SEPAEXECLP callback has the following options, which is indicated by the possible return values of
2690 * the 'result' variable (see type_sepa.h):
2691 * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
2692 * - adding an additional constraint (result SCIP_CONSADDED)
2693 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
2694 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
2695 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
2696 * (result SCIP_DIDNOTFIND)
2697 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
2698 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
2699 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
2700 *
2701 * @subsection SEPAEXECSOL
2702 *
2703 * The SEPAEXECSOL callback is executed during the separation loop on arbitrary primal solutions.
2704 * It should try to generate general purpose cutting planes in order to separate the given primal solution.
2705 * The method is not called in the LP solution loop, which means that there is no valid LP solution.
2706 *
2707 * In the standard SCIP environment, the SEPAEXECSOL callback is not used because only LP solutions are
2708 * separated. The SEPAEXECSOL callback provides means to support external relaxation handlers like semidefinite
2709 * relaxations that want to separate an intermediate primal solution vector. Thus, if you do not want to support
2710 * such external plugins, you do not need to implement this callback method.
2711 *
2712 * Usually, the callback searches and produces cuts, that are added with a call to SCIPaddCut().
2713 * If the cut should be added to the global cut pool, it calls SCIPaddPoolCut().
2714 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
2715 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
2716 * In addition to LP rows, the callback may also produce domain reductions or add other constraints.
2717 *
2718 * Overall, the SEPAEXECSOL callback has the following options, which is indicated by the possible return values of
2719 * the 'result' variable (see type_sepa.h):
2720 * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
2721 * - adding an additional constraint (result SCIP_CONSADDED)
2722 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
2723 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
2724 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
2725 * (result SCIP_DIDNOTFIND)
2726 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
2727 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
2728 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
2729 *
2730 *
2731 * @section SEPA_ADDITIONALCALLBACKS Additional Callback Methods of a Separator
2732 *
2733 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2734 * implemented for most applications, they can be used, for example, to initialize and free private data.
2735 * Additional callbacks can either be passed directly with SCIPincludeSepa() to SCIP or via specific
2736 * <b>setter functions</b> after a call of SCIPincludeSepaBasic(), see also @ref SEPA_INTERFACE.
2737 *
2738 * @subsection SEPAFREE
2739 *
2740 * If you are using separator data (see \ref SEPA_DATA and \ref SEPA_INTERFACE), you have to implement this method
2741 * in order to free the separator data. This can be done by the following procedure:
2742 *
2743 * @refsnippet{src/scip/sepa_gomory.c,SnippetSepaFreeGomory}
2744 *
2745 * If you have allocated memory for fields in your separator data, remember to free this memory
2746 * before freeing the separator data itself.
2747 * If you are using the C++ wrapper class, this method is not available.
2748 * Instead, just use the destructor of your class to free the member variables of your class.
2749 *
2750 * @subsection SEPACOPY
2751 *
2752 * The SEPACOPY callback is executed when a SCIP instance is copied, e.g. to
2753 * solve a sub-SCIP. By
2754 * defining this callback as
2755 * <code>NULL</code> the user disables the execution of the specified
2756 * separator for all copied SCIP instances. This may deteriorate the performance
2757 * of primal heuristics using sub-SCIPs.
2758 *
2759 * @subsection SEPAINIT
2760 *
2761 * The SEPAINIT callback is executed after the problem is transformed.
2762 * The separator may, e.g., use this call to initialize its separator data.
2763 * The difference between the original and the transformed problem is explained in
2764 * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
2765 *
2766 * @subsection SEPAEXIT
2767 *
2768 * The SEPAEXIT callback is executed before the transformed problem is freed.
2769 * In this method, the separator should free all resources that have been allocated for the solving process in SEPAINIT.
2770 *
2771 * @subsection SEPAINITSOL
2772 *
2773 * The SEPAINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
2774 * begin. The separator may use this call to initialize its branch-and-bound specific data.
2775 *
2776 * @subsection SEPAEXITSOL
2777 *
2778 * The SEPAEXITSOL callback is executed before the branch-and-bound process is freed. The separator should use this call
2779 * to clean up its branch-and-bound data, in particular to release all LP rows that it has created or captured.
2780 */
2781
2782/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2783
2784/**@page PROP How to add propagators
2785 *
2786 * Propagators are used to tighten the domains of the variables. Like for cutting planes, there are two different types
2787 * of domain propagations. Constraint based (primal) domain propagation algorithms are part of the corresponding
2788 * constraint handlers, see \ref CONSPROP. In contrast, domain propagators usually provide dual propagations, i.e.,
2789 * propagations that can be applied using the objective function and the current best known primal solution. This
2790 * section deals with such propagators.
2791 *
2792 * A complete list of all propagators contained in this release can be found \ref PROPAGATORS "here".
2793 *
2794 * We now explain how users can add their own propagators. Take the pseudo objective function propagator
2795 * (src/scip/prop_pseudoobj.c) as an example. As all other default plugins, it is written in C. C++ users can easily
2796 * adapt the code by using the scip::ObjProp wrapper base class and implement the @c scip_...() virtual methods instead
2797 * of the @c SCIP_DECL_PROP... callback methods.
2798 *
2799 * Additional documentation for the callback methods of a propagator can be found in the file type_prop.h.
2800 *
2801 * Here is what you have to do to implement a propagator:
2802 * -# Copy the template files src/scip/prop_xyz.c and src/scip/prop_xyz.h into files named "prop_mypropagator.c"
2803 * and "prop_mypropagator.h".
2804 * \n
2805 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2806 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2807 * -# Use `SCIPincludePropMypropagator()` in order to include the propagator into your SCIP instance,
2808 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2809 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2810 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypropagator".
2811 * -# Adjust the properties of the propagator (see \ref PROP_PROPERTIES).
2812 * -# Define the propagator data (see \ref PROP_DATA). This is optional.
2813 * -# Implement the interface methods (see \ref PROP_INTERFACE).
2814 * -# Implement the fundamental callback methods (see \ref PROP_FUNDAMENTALCALLBACKS).
2815 * -# Implement the additional callback methods (see \ref PROP_ADDITIONALCALLBACKS). This is optional.
2816 *
2817 * @section PROP_PROPERTIES Properties of a Propagator
2818 *
2819 * At the top of the new file "prop_mypropagator.c" you can find the propagator properties. These are given as compiler
2820 * defines. The presolving-related properties are optional,
2821 * they only have to be defined if the propagator supports presolving routines.
2822 * In the C++ wrapper class, you have to provide the propagator properties by calling the constructor of the
2823 * abstract base class scip::ObjProp from within your constructor. The properties you have the following meaning:
2824 *
2825 * @subsection PROP_FUNDAMENTALPROPERTIES Fundamental properties of a propagator
2826 *
2827 * \par PROP_NAME: the name of the propagator.
2828 * This name is used in the interactive shell to address the propagator. Additionally, if you are searching for a
2829 * propagator with SCIPfindProp(), this name is searched for. Names have to be unique: no two propagators may have the
2830 * same name.
2831 *
2832 * \par PROP_DESC: the description of the propagator.
2833 * This string is printed as a description of the propagator in the interactive shell.
2834 *
2835 * \par PROP_PRIORITY: the priority of the propagator.
2836 * In each propagation round, the propagators and propagation methods of the constraint handlers are called in a
2837 * predefined order, which is given by the priorities of the propagators and the check priorities of the constraint
2838 * handlers. First, the propagators with non-negative priority are called in order of decreasing priority. Next, the
2839 * propagation methods of the different constraint handlers are called in order of decreasing check priority. Finally,
2840 * the propagators with negative priority are called in order of decreasing priority. \n The priority of the
2841 * propagators should be set according to the complexity of the propagation algorithm and the impact of the domain
2842 * propagations: propagators providing fast algorithms that usually have a high impact (i.e., tighten many bounds)
2843 * should have a high priority.
2844 *
2845 * \par PROP_FREQ: the default frequency for propagating domains.
2846 * The frequency defines the depth levels at which the propagation method \ref PROPEXEC is called. For example, a
2847 * frequency of 7 means, that the propagation callback is executed for subproblems that are in depth 0, 7, 14, ... of
2848 * the branching tree. A frequency of 0 means that propagation is only applied in preprocessing and at the root node. A
2849 * frequency of -1 disables the propagator.
2850 * \n
2851 * The frequency can be adjusted by the user. This property of the propagator only defines the default value of the
2852 * frequency.\n
2853 * <b>Note:</b> If you want to have a more flexible control of when to execute the propagation algorithm, you have to
2854 * assign a frequency of 1 and implement a check at the beginning of your propagation algorithm whether you really want
2855 * to execute the domain propagation or not. If you do not want to execute it, set the result code to SCIP_DIDNOTRUN.
2856 *
2857 * \par PROP_DELAY: the default for whether the propagation method should be delayed, if other propagators or constraint handlers found domain reductions.
2858 * If the propagator's propagation method is marked to be delayed, it is only executed after no other propagator or
2859 * constraint handler found a domain reduction in the current iteration of the domain propagation loop. If the
2860 * propagation method of the propagator is very expensive, you may want to mark it to be delayed until all cheap
2861 * propagation methods have been executed.
2862 *
2863 * \par PROP_TIMING: the timing mask of the propagator.
2864 * SCIP calls the domain propagation routines at different places in the node processing loop.
2865 * This property indicates at which places the propagator is called.
2866 * Possible values are defined in type_timing.h and can be concatenated, e.g., as in SCIP_PROPTIMING_ALWAYS.
2867 *
2868 * @subsection PROP_ADDITIONALPROPERTIES Optional propagator properties
2869 *
2870 * The following properties are optional and only need to be defined if the propagator supports
2871 * presolving, that is, if the \ref PROPPRESOL "presolving callback" is implemented.
2872
2873 * \par PROP_PRESOLTIMING: the timing of the presolving method (FAST, MEDIUM, or EXHAUSTIVE).
2874 * Every presolving round starts with the FAST presolving methods. MEDIUM presolvers are only called, if FAST presolvers did not find
2875 * enough reductions in this round so far, and EXHAUSTIVE presolving steps are only performed if all presolvers called before
2876 * in this round were unsuccessful.
2877 * Presolving methods should be assigned a timing based on how expensive they are, e.g., presolvers that provide fast algorithms that
2878 * usually have a high impact (i.e., remove lots of variables or tighten bounds of many variables) should have a timing FAST.
2879 * If a presolving method implements different algorithms of different complexity, it may also get multiple timings and check the timing
2880 * internally in the \ref PROPPRESOL callback to decide which algorithms to run.
2881 *
2882 * \par PROP_PRESOL_PRIORITY: the priority of the presolving method.
2883 * This attribute is analogous to the PROP_PRIORITY flag, but deals with the preprocessing method of the presolver.
2884 *
2885 * \par PROP_PRESOL_MAXROUNDS: the default maximal number of presolving rounds the propagator participates in.
2886 * The preprocessing is executed in rounds.
2887 * If enough changes have been applied to the model, an additional preprocessing round is performed.
2888 * The MAXROUNDS parameter of a propagator denotes the maximal number of preprocessing rounds, the propagator
2889 * participates in.
2890 * A value of -1 means, that there is no limit on the number of rounds.
2891 * A value of 0 means, the preprocessing callback of the propagator is disabled.
2892 *
2893 * @section PROP_DATA Propagator Data
2894 *
2895 * Below the title "Data structures" you can find a struct called <code>struct SCIP_PropData</code>. In this data
2896 * structure, you can store the data of your propagator. For example, you should store the adjustable parameters of the
2897 * propagator in this data structure. If you are using C++, you can add propagator data as object variables to your
2898 * class as usual .
2899 * \n
2900 * Defining propagator data is optional. You can leave the struct empty.
2901 *
2902 *
2903 * @section PROP_INTERFACE Interface Methods
2904 *
2905 * At the bottom of "prop_mypropagator.c", you can find the interface method SCIPincludeSepaMypropagator(),
2906 * which also appears in "prop_mypropagator.h"
2907 * SCIPincludePropMypropagator() is called by the user, if (s)he wants to include the propagator,
2908 * i.e., if (s)he wants to use the propagator in his/her application.
2909 *
2910 * This method only has to be adjusted slightly.
2911 * It is responsible for notifying SCIP of the presence of the propagator. For this, you can either call SCIPincludeProp(),
2912 * or SCIPincludePropBasic() since SCIP version 3.0. In the latter variant, \ref PROP_ADDITIONALCALLBACKS "additional callbacks"
2913 * must be added via setter functions as, e.g., SCIPsetPropCopy(). We recommend this latter variant because
2914 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2915 * variant must be manually adjusted with every SCIP release containing new callbacks for separators in order to compile.
2916 *
2917 *
2918 * If you are using propagator data, you have to allocate the memory for the data at this point. You can do this by
2919 * calling
2920 * \code
2921 * SCIP_CALL( SCIPallocBlockMemory(scip, &propdata) );
2922 * \endcode
2923 * You also have to initialize the fields in <code>struct SCIP_PropData</code> afterwards.
2924 *
2925 * You may also add user parameters for your propagator, see the method SCIPincludePropPseudoobj() in
2926 * src/scip/prop_pseudoobj.c for an example.
2927 *
2928 *
2929 * @section PROP_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Propagator
2930 *
2931 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2932 * an operational algorithm.
2933 * They are passed together with the propagator itself to SCIP using SCIPincludeProp() or SCIPincludePropBasic(),
2934 * see @ref PROP_INTERFACE.
2935 *
2936 * Propagator plugins have one fundamental callback method, namely the \ref PROPEXEC method
2937 * method. This method has to be implemented for every propagator; the other callback methods are optional. In the
2938 * C++ wrapper class scip::ObjProp, the scip_exec() method (which corresponds to the \ref PROPEXEC
2939 * callback) is a virtual abstract member function. You have to
2940 * implement it in order to be able to construct an object of your propagator class.
2941 *
2942 * Additional documentation for the callback methods can be found in type_prop.h.
2943 *
2944 * @subsection PROPEXEC
2945 *
2946 * The PROPEXEC callback is called during presolving and during the subproblem processing. It should perform the actual
2947 * domain propagation, which means that it should tighten the variables' bounds. The technique of domain propagation,
2948 * which is the main workhorse of constraint programming, is called "node preprocessing" in the Integer Programming
2949 * community.
2950 *
2951 * The PROPEXEC callback has the following options:
2952 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
2953 * - reducing (i.e, tightening) the domains of some variables (result SCIP_REDUCEDDOM)
2954 * - stating that the propagator searched, but did not find domain reductions, cutting planes, or cut constraints
2955 * (result SCIP_DIDNOTFIND)
2956 * - stating that the propagator was skipped (result SCIP_DIDNOTRUN)
2957 * - stating that the propagator was skipped, but should be called again (result SCIP_DELAYED)
2958 *
2959 *
2960 *
2961 * @section PROP_ADDITIONALCALLBACKS Additional Callback Methods of a Propagator
2962 *
2963 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2964 * implemented for most applications, they can be used, for example, to initialize and free private data.
2965 * Additional callbacks can either be passed directly with SCIPincludeProp() to SCIP or via specific
2966 * <b>setter functions</b> after a call of SCIPincludePropBasic(), see also @ref PROP_INTERFACE.
2967 *
2968 * @subsection PROPRESPROP
2969 *
2970 * If the propagator wants to support \ref CONF "conflict analysis", it has to supply the PROPRESPROP method. It also should call
2971 * SCIPinferVarLbProp() or SCIPinferVarUbProp() in the domain propagation instead of SCIPchgVarLb() or SCIPchgVarUb() in
2972 * order to deduce bound changes on variables. In the SCIPinferVarLbProp() and SCIPinferVarUbProp() calls, the
2973 * propagator provides a pointer to itself and an integer value "inferinfo" that can be arbitrarily chosen.
2974 *
2975 * The propagation conflict resolving method PROPRESPROP must then be implemented to provide the "reasons" for the bound
2976 * changes, i.e., the bounds of variables at the time of the propagation, which forced the propagator to set the
2977 * conflict variable's bound to its current value. It can use the "inferinfo" tag to identify its own propagation rule
2978 * and thus identify the "reason" bounds. The bounds that form the reason of the assignment must then be provided by
2979 * calls to SCIPaddConflictLb() and SCIPaddConflictUb() in the propagation conflict resolving method.
2980 *
2981 * See the description of the propagation conflict resolving method \ref CONSRESPROP of constraint handlers for
2982 * further details.
2983 *
2984 * Omitting the PROPRESPROP callback circumvents the implementation of the usually rather complex conflict resolving method.
2985 * Yet, it
2986 * will make the conflict analysis less effective. We suggest to first omit the conflict resolving method and check how
2987 * effective the propagation method is. If it produces a lot of propagations for your application, you definitely should
2988 * consider implementing the conflict resolving method.
2989 *
2990 *
2991 * @subsection PROPFREE
2992 *
2993 * If you are using propagator data, you have to implement this method in order to free the propagator data.
2994 * This can be done by the following procedure:
2995 *
2996 * @refsnippet{src/scip/prop_redcost.c,SnippetPropFreeRedcost}
2997 *
2998 * If you have allocated memory for fields in your propagator data, remember to free this memory
2999 * before freeing the propagator data itself.
3000 * If you are using the C++ wrapper class, this method is not available.
3001 * Instead, just use the destructor of your class to free the member variables of your class.
3002 *
3003 * @subsection PROPINIT
3004 *
3005 * The PROPINIT callback is executed after the problem is transformed. The propagator may, e.g., use this call to
3006 * initialize its propagator data.
3007 *
3008 * @subsection PROPCOPY
3009 *
3010 * The PROPCOPY callback is executed when a SCIP instance is copied, e.g. to
3011 * solve a sub-SCIP. By
3012 * defining this callback as
3013 * <code>NULL</code> the user disables the execution of the specified
3014 * propagator for all copied SCIP instances. This may deteriorate the performance
3015 * of primal heuristics using sub-SCIPs.
3016 *
3017 * @subsection PROPEXIT
3018 *
3019 * The PROPEXIT callback is executed before the transformed problem is freed.
3020 * In this method, the propagator should free all resources that have been allocated for the solving process in PROPINIT.
3021 *
3022 * @subsection PROPINITPRE
3023 *
3024 * The PROPINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
3025 * The propagator may use this call to initialize its presolving data before the presolving process begins.
3026 *
3027 * @subsection PROPEXITPRE
3028 *
3029 * The PROPEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
3030 * The propagator may use this call, e.g., to clean up its presolving data.
3031 * Besides clean up, no time consuming operations should be done.
3032 *
3033 * @subsection PROPINITSOL
3034 *
3035 * The PROPINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3036 * begin.
3037 * The propagator may use this call to initialize its branch-and-bound specific data.
3038 *
3039 * @subsection PROPEXITSOL
3040 *
3041 * The PROPEXITSOL callback is executed before the branch-and-bound process is freed.
3042 * The propagator should use this call to clean up its branch-and-bound data.
3043 *
3044 * @subsection PROPPRESOL
3045 *
3046 * Seaches for domain propagations, analogous to the \ref PROPEXEC callback.
3047 * However, this callback is called during preprocessing.
3048 *
3049 * To inform SCIP that the presolving method found a reduction the result pointer has to be set in a proper way.
3050 * The following options are possible:
3051 *
3052 * - SCIP_UNBOUNDED : at least one variable is not bounded by any constraint in objective direction
3053 * - SCIP_CUTOFF : at least one domain reduction that renders the problem infeasible has been found
3054 * - SCIP_SUCCESS : the presolver found a domain reduction
3055 * - SCIP_DIDNOTFIND : the presolver searched, but did not find a presolving change
3056 * - SCIP_DIDNOTRUN : the presolver was skipped
3057 * - SCIP_DELAYED : the presolver was skipped, but should be called again
3058 *
3059 *
3060 * Please see also the @ref PROP_ADDITIONALPROPERTIES section to learn about the properties
3061 * PROP_PRESOLTIMING and PROP_PRESOL_MAXROUNDS, which influence the behaviour of SCIP
3062 * calling PROPPRESOL.
3063 *
3064 */
3065
3066/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3067
3068/**@page BRANCH How to add branching rules
3069 *
3070 * Branching rules are used to split the problem at the current node into smaller subproblems. Branching rules can be called at three
3071 * different occasions, which is why they have three different execution methods (see \ref
3072 * BRANCHRULE_ADDITIONALCALLBACKS). Branching is performed if:
3073 * - the LP solution of the current problem is fractional. In this case, the integrality constraint handler calls the
3074 * \ref BRANCHEXECLP methods of the branching rules.
3075 * - the list of external branching candidates is not empty. This will only be the case if branching candidates were added
3076 * by a user's \ref RELAX "relaxation handler" or \ref CONS "constraint handler" plugin, calling SCIPaddExternBranchCand().
3077 * These branching candidates should be processed by the \ref BRANCHEXECEXT method.
3078 * - if an integral solution violates one or more constraints and this infeasibility could not be resolved in the callback methods
3079 * \ref CONSENFOLP and \ref CONSENFOPS of the corresponding constraint handlers. In this case, the \ref BRANCHEXECPS method will be called. This is the
3080 * 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
3081 * branching on pseudo solutions works as a last resort.
3082 *
3083 * The idea of branching rules is to take a global view on the problem. In contrast, branching paradigms which are
3084 * specific to one type of constraint are best implemented within the enforcement callbacks of your constraint handler.
3085 * See, e.g., the constraint specific branching rules provided by the constraint handlers for special ordered sets
3086 * (src/scip/cons_sos{1,2}.c)).
3087 * \n
3088 * All branching rules that come with the default distribution of SCIP create two subproblems by splitting a single
3089 * variable's domain. It is, however, fully supported to implement much more general branching schemes, for example by
3090 * creating more than two subproblems, or by adding additional constraints to the subproblems instead of tightening the
3091 * domains of the variables.
3092 * \n
3093 * A complete list of all branching rules contained in this release can be found \ref BRANCHINGRULES "here".
3094 * However, note that constraint handlers can implement their own branching when enforcing constraints.
3095 * In particular the handler for nonlinear constraints currently does not use the branching plugins for spatial branching
3096 * by default. Its behavior can be adjusted with the parameters in category constraints/nonlinear/branching.
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 * @subsection NLHDLRSOLLINEARIZE
4784 *
4785 * This callback is called by the constraint handler when it has caught a solution event from SCIP and option constraints/nonlinear/linearizeheursol has been enabled.
4786 * The constraint handler then calls the nonlinear handlers for all expressions they currently handle.
4787 * The nonlinear handler may use this opportunity to add a cut that supports its nonlinear function in the given solution to the cutpool.
4788 * For convex functions, this may help to accellerate proving optimality for a solution found by a NLP solver.
4789 */
4790
4791/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4792
4793/**@page DIVINGHEUR How to implement a diving heuristic
4794 *
4795 * Diving heuristics are an important addon to the branch-and-cut search. A diving heuristic explores a single probing
4796 * path down the search tree. In contrast to the regular search guided by branching rule(s) and the selected
4797 * node selector, the diving is performed in an auxiliary tree originating from the focus node of the main
4798 * search tree where the heuristic was called. The advantage of this approach is that many different scoring mechanisms
4799 * can be safely tried as diving heuristic and may probably lead to better solutions. SCIP has a lot of diving heuristics
4800 * included in its default plugin set.
4801 * \n
4802 *
4803 * Since SCIP version 3.2, the diving heuristics have been redesigned to contain mainly the scoring function used by the
4804 * heuristic. In order to implement a user-defined diving heuristic, it is possible to create one (or several)
4805 * divesets that control the scoring mechanism and add them to the primal heuristic. This has the advantage that
4806 * less code is necessary to create a working diving heuristic. The SCIP statistics now also display some interesting statistics
4807 * about every diveset together in the section 'Diving Statistics'.
4808 * \n
4809 *
4810 * This page contains the necessary steps to understand and include a diveset into ones primal diving heuristic plugin. As
4811 * a prerequisite, you should understand the basic implementation steps for a primal heuristic, see \ref HEUR.
4812 * In order to make use of divesets, they must be included _after_ the primal heuristic to which they should belong
4813 * has been included, by using SCIPincludeDiveset(). This will create the data structure for the diveset and
4814 * append it to the list of divesets belonging to the heuristic, which can be retrieved later together with their number
4815 * by using SCIPheurGetDivesets() and SCIPheurGetNDivesets(), respectively. No further memory allocation or deletion is needed;
4816 * As a member of the heuristic, SCIP automatically takes care of freeing the diveset when it is exiting.
4817 * \n
4818 *
4819 * Before the inclusion, one may think of adjusting the various properties that a diveset offers to control
4820 * the behavior of the algorithm. These are subject to the following section.
4821 * \n
4822 *
4823 * It is mandatory to implement the fundamental scoring callback of the diveset, which is explained in more detail
4824 * in Section \ref DIVING_FUNDAMENTALCALLBACKS.
4825 * \n
4826 *
4827 * Once the properties have been carefully adjusted and the scoring
4828 * has been defined, use the method SCIPperformGenericDivingAlgorithm() inside the execution callback (\ref HEUREXEC) of the primal
4829 * heuristic to which the diveset belongs, after checking possible preliminaries that may not be met at all times of the search.
4830 * \n
4831 *
4832 * For a code example, we refer to \ref heur_guideddiving.h, which guides the diving into the direction of the current incumbent solution.
4833 * Before it calls SCIPperformGenericDivingAlgorithm(), it checks whether an incumbent is available, and returns if there is none.
4834 *
4835 *
4836 * @section DIVING_PARAMETERS User parameters and properties for every diveset
4837 *
4838 * Every diveset controls the diving behavior through a set of user-defined parameters, which are explained in the following:
4839 *
4840 * \par MINRELDEPTH
4841 * the minimal relative depth (to the maximum depth explored during regular search) of the current focus node to start diving
4842 *
4843 * \par MAXRELDEPTH
4844 * the maximal relative depth (to the maximum depth explored during regular search) of the current focus node to start diving
4845 *
4846 * \par MAXLPITERQUOT
4847 * maximal fraction of diving LP iterations compared to node LP iterations that this dive controller may consume
4848 *
4849 * \par MAXLPITEROFS
4850 * an additional number of allowed LP iterations
4851 *
4852 * \par MAXDIVEUBQUOT
4853 * maximal quotient (curlowerbound - lowerbound)/(cutoffbound - lowerbound)
4854 * where diving is performed (0.0: no limit)
4855 *
4856 * \par MAXDIVEAVGQUOT
4857 * maximal quotient (curlowerbound - lowerbound)/(avglowerbound - lowerbound)
4858 * where diving is performed (0.0: no limit)
4859 *
4860 * \par MAXDIVEUBQUOTNOSOL
4861 * maximal UBQUOT when no solution was found yet (0.0: no limit)
4862 *
4863 * \par MAXDIVEAVGQUOTNOSOL
4864 * maximal AVGQUOT when no solution was found yet (0.0: no limit)
4865 *
4866 * \par BACKTRACK
4867 * use one level of backtracking if infeasibility is encountered?
4868 *
4869 * \par LPRESOLVEDOMCHGQUOT
4870 * parameter to control LP resolve dynamically based on this percentage of observed bound changes relative to all variables or
4871 * the LP branching candidates (integer variables with fractional solution values) from the last node where an LP has been solved.
4872 * This property has no effect when the LPSOLVEFREQ is set to 1.
4873 *
4874 * \par LPSOLVEFREQ
4875 * 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
4876 * diveset to solve _all_ intermediate LPs) or 0 to only resolve the LP relaxation after propagation found at least a certain percentage
4877 * domain changes, see also the previous LPRESOLVEDOMCHGQUOT parameter.
4878 *
4879 * \par ONLYLPBRANCHCANDS
4880 * Set this property to TRUE if only LP branching candidates be considered for the execution of the diving algorithm instead of the slower but
4881 * more general constraint handler diving variable selection.
4882 *
4883 * \par DIVETYPES
4884 * bit mask that represents all supported dive types. Irrelevant if only LP branching candidates should be scored, otherwise, different
4885 * constraint handlers may ask the diveset if it supports their preferred divetype. See \ref type_heur.h for a list of
4886 * available dive types.
4887 *
4888 * @section DIVING_FUNDAMENTALCALLBACKS Fundamental callbacks of a diveset
4889 *
4890 * Only one callback is necessary to complete a diveset to guide the diving search performed:
4891 *
4892 * @subsection DIVESETGETSCORE
4893 *
4894 * The scoring callback expects a candidate variable and calculates a score value and a preferred direction. The selected
4895 * variable for diving will be one that _maximizes_ the score function provided by the diveset.
4896 * If the diveset should support more than one possible type of diving, it may use the divetype argument as a hint how
4897 * the caller of the score function (could be the diving algorithm itself or one of the constraint handlers that
4898 * implement diving variable selection) intends to perform the search.
4899 *
4900 * @section DIVING_FURTHERINFO Further information
4901 *
4902 * This is all there is to extend the SCIP set of diving heuristics by a new one. For further information, please see
4903 * diveset related methods in \ref type_heur.h, \ref pub_heur.h, \ref heuristics.h, and \ref heur_guideddiving.h or
4904 * other diving heuristics that implement diving through a diveset.
4905 */
4906
4907/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4908
4909/**@page RELAX How to add relaxation handlers
4910 *
4911 * SCIP provides specific support for LP relaxations of constraint integer programs. In addition, relaxation handlers,
4912 * also called relaxators, can be used to include other relaxations, e.g. Lagrange relaxations or semidefinite
4913 * relaxations. The relaxation handler manages the necessary data structures and calls the relaxation solver to generate dual
4914 * bounds and primal solution candidates.
4915 * \n
4916 * However, the data to define a single relaxation must either be extracted by the relaxation handler itself (e.g., from
4917 * the user defined problem data, the LP information, or the integrality conditions), or it must be provided by the constraint
4918 * handlers. In the latter case, the constraint handlers have to be extended to support this specific relaxation.
4919 * \n
4920 *
4921 * We now explain how users can add their own relaxation handlers using the C interface. As an example, look into the NLP
4922 * relaxation handler of the \ref RELAXATOR_MAIN "Relaxator example" (examples/Relaxator/src/relax_nlp.c). It is very easy to
4923 * transfer the C explanation to C++: whenever a method should be implemented using the SCIP_DECL_RELAX... notion,
4924 * reimplement the corresponding virtual member function of the abstract scip::ObjRelax wrapper base class.
4925 *
4926 * Additional documentation for the callback methods of a relaxation handler can be found in the file type_relax.h.
4927 *
4928 * Here is what you have to do to implement a relaxation handler:
4929 * -# Copy the template files src/scip/relax_xyz.c and src/scip/relax_xyz.h into files named "relax_myrelaxator.c"
4930 * and "relax_myrelaxator.h".
4931 * \n
4932 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
4933 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
4934 * -# Use `SCIPincludeRelaxMyrelaxator()` in order to include the relaxation handler into your SCIP instance,
4935 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
4936 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
4937 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myrelaxator".
4938 * -# Adjust the properties of the relaxation handler (see \ref RELAX_PROPERTIES).
4939 * -# Define the relaxation handler data (see \ref RELAX_DATA). This is optional.
4940 * -# Implement the interface methods (see \ref RELAX_INTERFACE).
4941 * -# Implement the fundamental callback methods (see \ref RELAX_FUNDAMENTALCALLBACKS).
4942 * -# Implement the additional callback methods (see \ref RELAX_ADDITIONALCALLBACKS). This is optional.
4943 *
4944 *
4945 * @section RELAX_PROPERTIES Properties of a Relaxation Handler
4946 *
4947 * At the top of the new file "relax_myrelaxator.c" you can find the relaxation handler properties,
4948 * which are given as compiler defines.
4949 * In the C++ wrapper class, you have to provide the relaxation handler properties by calling the constructor
4950 * of the abstract base class scip::ObjRelax from within your constructor.
4951 * The properties have the following meaning:
4952 *
4953 * \par RELAX_NAME: the name of the relaxation handler.
4954 * This name is used in the interactive shell to address the relaxation handler.
4955 * Additionally, if you are searching for a relaxation handler with SCIPfindRelax(), this name is looked up.
4956 * Names have to be unique: no two relaxation handlers may have the same name.
4957 *
4958 * \par RELAX_DESC: the description of the relaxation handler.
4959 * This string is printed as a description of the relaxation handler in the interactive shell.
4960 *
4961 * \par RELAX_PRIORITY: the priority of the relaxation handler.
4962 * During each relaxation solving round, the included relaxation handlers and the
4963 * price-and-cut loop for solving the LP relaxation are called in a predefined order, which is given by the priorities
4964 * of the relaxation handlers.
4965 * First, the relaxation handlers with non-negative priority are called in the order of decreasing priority.
4966 * Next, the price-and-cut loop for solving the LP relaxation is executed.
4967 * Finally, the relaxation handlers with negative priority are called in the order of decreasing priority.
4968 * \n
4969 * Usually, you will have only one relaxation handler in your application and thus only have to decide whether it should
4970 * be called before or after solving the LP relaxation. For this decision you should consider the complexity of
4971 * the relaxation solving algorithm and the impact of the resulting solution: if your relaxation handler provides a fast
4972 * algorithm that usually has a high impact (i.e. the relaxation is a good approximation of the
4973 * feasible region of the subproblem and the solution severely improves the dual bound), it should have a non-negative
4974 * priority.
4975 * \n
4976 * Note that for certain applications, it is useful to disable the LP relaxation and only use your custom relaxation.
4977 * This can easily be achieved by setting the "lp/solvefreq" parameter to -1.
4978 *
4979 * \par RELAX_FREQ: the default frequency for solving the relaxation.
4980 * The frequency defines the depth levels at which the relaxation solving method \ref RELAXEXEC is called.
4981 * For example, a frequency of 7 means, that the relaxation solving callback is executed for subproblems that are in depth
4982 * 0, 7, 14, ... of the branching tree. A frequency of 0 means that the callback is only executed at the root node, i.e.,
4983 * only the relaxation of the root problem is solved. A frequency of -1 disables the relaxation handler.
4984 *
4985 *
4986 *
4987 * @section RELAX_DATA Relaxation Handler Data
4988 *
4989 * Below the header "Data structures" you can find a struct which is called "struct SCIP_RelaxData".
4990 * In this data structure, you can store the data of your relaxation handler. For example, you should store the adjustable
4991 * parameters of the relaxation handler in this data structure.
4992 * If you are using C++, you can add relaxation handler data as usual as object variables to your class.
4993 * \n
4994 * Defining relaxation handler data is optional. You can leave the struct empty.
4995 *
4996 *
4997 * @section RELAX_INTERFACE Interface Methods
4998 *
4999 * At the bottom of "relax_myrelaxator.c", you can find the interface method SCIPincludeRelaxMyrelaxator(),
5000 * which also appears in "relax_myrelaxator.h".
5001 * SCIPincludeRelaxMyrelaxator() is called by the user, if (s)he wants to include the relaxation handler,
5002 * i.e., if (s)he wants to use the relaxation handler in his/her application.
5003 *
5004 * This method only has to be adjusted slightly.
5005 * It is responsible for notifying SCIP of the presence of the relaxation handler. For this, you can either call
5006 * SCIPincludeRelax(),
5007 * or SCIPincludeRelaxBasic() since SCIP version 3.0. In the latter variant, \ref RELAX_ADDITIONALCALLBACKS "additional callbacks"
5008 * must be added via setter functions as, e.g., SCIPsetRelaxCopy(). We recommend this latter variant because
5009 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
5010 * variant must be manually adjusted with every SCIP release containing new callbacks for relaxation handlers in order to compile.
5011 *
5012 * If you are using relaxation handler data, you have to allocate the memory for the data at this point.
5013 * You can do this by calling:
5014 * \code
5015 * SCIP_CALL( SCIPallocBlockMemory(scip, &relaxdata) );
5016 * \endcode
5017 * You also have to initialize the fields in struct SCIP_RelaxData afterwards.
5018 *
5019 * You may also add user parameters for your relaxation handler, see the method SCIPincludeConshdlrKnapsack() in
5020 * the \ref cons_knapsack.h "knapsack constraint handler" for an example of how to add user parameters.
5021 *
5022 *
5023 * @section RELAX_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Relaxation Handler
5024 *
5025 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
5026 * an operational algorithm.
5027 * They are passed together with the relaxation handler itself to SCIP using SCIPincludeRelax() or SCIPincludeRelaxBasic(),
5028 * see @ref RELAX_INTERFACE.
5029 *
5030 *
5031 * Relaxation handler plugins have only one fundamental callback method, namely the \ref RELAXEXEC method.
5032 * This method has to be implemented for every relaxation handler; the other callback methods are optional.
5033 * In the C++ wrapper class scip::ObjRelax, the scip_exec() method (which corresponds to the \ref RELAXEXEC callback) is a virtual
5034 * abstract member function.
5035 * You have to implement it in order to be able to construct an object of your relaxation handler class.
5036 *
5037 * Additional documentation for the callback methods can be found in type_relax.h.
5038 *
5039 * @subsection RELAXEXEC
5040 * The RELAXEXEC is called in each relaxation solving round. It should solve the current
5041 * subproblem's relaxation.
5042 *
5043 * Note that, like the LP relaxation, the relaxation handler should only operate on variables for which the corresponding
5044 * column exists in the transformed problem. Typical methods called by a relaxation handler are SCIPconstructLP() and SCIPflushLP() to
5045 * make sure that the LP of the current node is constructed and its data can be accessed via calls to SCIPgetLPRowsData()
5046 * and SCIPgetLPColsData(), and SCIPseparateSol() to call the cutting plane separators for a given primal solution.
5047 *
5048 * The lowerbound computed by the relaxation should be returned in the lowerbound pointer. If the relaxation improves on the best
5049 * relaxation already computed (either <code>SCIPisRelaxSolValid()</code> returns FALSE, meaning that no relaxation solution
5050 * is available so far, or the lowerbound is larger than the value returned by <code>SCIPgetRelaxSolObj()</code>), then the primal
5051 * solution of the relaxation should be stored inside the data structures of SCIP with <code>SCIPsetRelaxSolVal()</code>,
5052 * <code>SCIPsetRelaxSolVals()</code> or <code>SCIPsetRelaxSolValsSol()</code>. If you set the values one by one, you will need to call
5053 * <code>SCIPmarkRelaxSolValid()</code> to inform SCIP that the solution is complete and valid. With the "includeslp" argument of
5054 * <code>SCIPsetRelaxSolVals()</code>, <code>SCIPsetRelaxSolValsSol()</code> and <code>SCIPmarkRelaxSolValid()</code> you need to tell SCIP
5055 * 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
5056 * lowerbound of this relaxator is larger than the LP's. You may also call SCIPtrySolFree() directly from the
5057 * relaxation handler to make sure that a solution is added to the solution storage if it is feasible, even if the relaxator does not
5058 * include the LP or another relaxator produced a stronger bound. Also note that when setting the values of the relaxation solution one by one,
5059 * the objective value of the relaxation solution will be updated incrementally. If the whole solution should be updated, using SCIPsetRelaxSolVals()
5060 * instead or calling SCIPclearRelaxSolVals() before setting the first value to reset the solution and the objective value to 0 may help the numerics.
5061 * Furthermore, there is a list of external branching candidates, that can be filled by relaxation handlers and constraint handlers,
5062 * allowing branching rules to take these candidates as a guide on how to split the problem into subproblems. If the relaxation
5063 * solution is enforced, the integrality constraint handler will add external branching candidates for the relaxation solution
5064 * automatically, but the relaxation handler can also directly call <code>SCIPaddExternBranchCand()</code>.
5065 *
5066 * Usually, the RELAXEXEC callback only solves the relaxation and provides a lower (dual) bound through the corresponding pointer and
5067 * possibly a solution through <code>SCIPsetRelaxSolVal()</code> calls.
5068 * However, it may also produce domain reductions, add additional constraints or generate cutting planes. It has the
5069 * following options:
5070 * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
5071 * - adding an additional constraint and stating that the relaxation handler should not be called again on the same
5072 * relaxation (result SCIP_CONSADDED)
5073 * - reducing a variable's domain and stating that the relaxation handler should not be called again on the same
5074 * relaxation (result SCIP_REDUCEDDOM)
5075 * - adding a cutting plane to the LP and stating that the relaxation handler should not be called again on the same
5076 * relaxation (result SCIP_SEPARATED)
5077 * - stating that the relaxation handler solved the relaxation and should not be called again on the same relaxation
5078 * (result SCIP_SUCCESS)
5079 * - interrupting the solving process to wait for additional input, e.g., cutting planes (result SCIP_SUSPENDED)
5080 * - stating that the separator was skipped (result SCIP_DIDNOTRUN).
5081 *
5082 * In the above criteria, "the same relaxation" means that the LP relaxation stayed unmodified. This means in particular
5083 * that no row has been added and no bounds have been modified. For example, changing the bounds of a variable will, as
5084 * long as it was a COLUMN variable, lead to a modification in the LP such that the relaxation handler is called again
5085 * after it returned with the result code SCIP_REDUCEDDOM. If the relaxation solution should be enforced, the relaxation
5086 * handler has to produce a new solution in this case which satisfies the updated LP. If a relaxation handler should only run
5087 * once per node to compute a lower bound, it should store the node of the last relaxation call itself and return
5088 * SCIP_DIDNOTRUN for subsequent calls in the same node.
5089 *
5090 *
5091 * @section RELAX_ADDITIONALCALLBACKS Additional Callback Methods of a Relaxation Handler
5092 *
5093 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
5094 * implemented for most applications, they can be used, for example, to initialize and free private data.
5095 * Additional callbacks can either be passed directly with SCIPincludeRelax() to SCIP or via specific
5096 * <b>setter functions</b> after a call of SCIPincludeRelaxBasic(), see also @ref RELAX_INTERFACE.
5097 *
5098 * @subsection RELAXFREE
5099 *
5100 * If you are using relaxation handler data, you have to implement this method in order to free the relaxation handler
5101 * data. This can be done by the following procedure:
5102 *
5103 * @refsnippet{tests/src/relax/relax.c,SnippetRelaxFreeUnittest}
5104 *
5105 * If you have allocated memory for fields in your relaxation handler data, remember to free this memory
5106 * before freeing the relaxation handler data itself.
5107 * If you are using the C++ wrapper class, this method is not available.
5108 * Instead, just use the destructor of your class to free the member variables of your class.
5109 *
5110 * @subsection RELAXINIT
5111 *
5112 * The RELAXINIT callback is executed after the problem is transformed.
5113 * The relaxation handler may, e.g., use this call to initialize its relaxation handler data.
5114 *
5115 * @subsection RELAXCOPY
5116 *
5117 * The RELAXCOPY callback is executed when a SCIP instance is copied, e.g. to
5118 * solve a sub-SCIP. By
5119 * defining this callback as
5120 * <code>NULL</code> the user disables the execution of the specified
5121 * relaxation handler for all copied SCIP instances. This may deteriorate the performance
5122 * of primal heuristics using sub-SCIPs.
5123 *
5124 * @subsection RELAXEXIT
5125 *
5126 * The RELAXEXIT callback is executed before the transformed problem is freed.
5127 * In this method, the relaxation handler should free all resources that have been allocated for the solving process in
5128 * RELAXINIT.
5129 *
5130 * @subsection RELAXINITSOL
5131 *
5132 * The RELAXINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
5133 * begin. The relaxation handler may use this call to initialize its branch-and-bound specific data.
5134 *
5135 * @subsection REALXEXITSOL
5136 *
5137 * The RELAXEXITSOL callback is executed before the branch-and-bound process is freed.
5138 * The relaxation handler should use this call to clean up its branch-and-bound data.
5139 */
5140
5141/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5142
5143/**@page READER How to add file readers
5144 *
5145 * Mainly, file readers are called to parse an input file and generate a constraint integer programming model. They
5146 * create constraints and variables and activate variable pricers if necessary. However, they can also be called, for
5147 * example, to parse an input file containing information about a primal solution or fixing of variables. Besides that
5148 * it is possible to use some of them for writing (exporting) the problem in a specific format. \n A complete list of
5149 * all file readers contained in this release can be found \ref FILEREADERS "here".
5150 *
5151 * Since a file reader is also responsible for writing a file, the user may
5152 * ask why the readers have not the name "filehandler". This name would
5153 * represent this plugin much better than the used one.
5154 * \n
5155 * The used name "readers" is historically grown. In the beginning of SCIP
5156 * there was no need to write/export problems. Therefore, the the plugin
5157 * name "readers" was best fitting for this plugin since only reading was essential.
5158 * It turned out, however, that it is quite nice to write/export certain subproblem during
5159 * the solving process mainly for debugging. Therefore, a writing callback
5160 * was added to the "readers" plugin.
5161 *
5162 * We now explain how users can add their own file readers.
5163 * Take the file reader for MIPs in IBM's Mathematical Programming System format (src/scip/reader_mps.c) as an example.
5164 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjReader wrapper
5165 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_READER... callback methods.
5166 *
5167 * Additional documentation for the callback methods of a file reader can be found in the file type_reader.h.
5168 *
5169 * Here is what you have to do to implement a file reader named "myreader" in C:
5170 * -# Copy the template files src/scip/reader_xyz.c and src/scip/reader_xyz.h into files named
5171 * "reader_myreader.c" and "reader_myreader.h".
5172 * \n
5173 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5174 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5175 * -# Use `SCIPincludeReaderMyreader()` in order to include the reader into your SCIP instance,
5176 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5177 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5178 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myreader".
5179 * -# Adjust the \ref READER_PROPERTIES "properties of the file reader".
5180 * -# Define the \ref READER_DATA "file reader data". This is optional.
5181 * -# Implement the \ref READER_INTERFACE "interface methods".
5182 * -# Implement the \ref READER_FUNDAMENTALCALLBACKS "fundamental callback methods".
5183 * -# Implement the \ref READER_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5184 *
5185 *
5186 * @section READER_PROPERTIES Properties of a File Reader
5187 *
5188 * At the top of the new file "reader_myreader.c" you can find the file reader properties.
5189 * These are given as compiler defines.
5190 * In the C++ wrapper class, you have to provide the file reader properties by calling the constructor
5191 * of the abstract base class scip::ObjReader from within your constructor.
5192 * The properties you have to set have the following meaning:
5193 *
5194 * \par READER_NAME: the name of the file reader.
5195 * This name is used in the interactive shell to address the file reader.
5196 * Additionally, if you are searching for a file reader with SCIPfindReader(), this name is looked up.
5197 * Names have to be unique: no two file readers may have the same name.
5198 *
5199 * \par READER_DESC: the description of the file reader.
5200 * This string is printed as a description of the file reader in the interactive shell.
5201 *
5202 * \par READER_EXTENSION: the file name extension of the file reader.
5203 * Each file reader is hooked to a single file name extension. It is automatically called if the user wants to read in a
5204 * file of corresponding name. The extensions of the different file readers have to be unique.
5205 * Note that the additional extension '.gz', '.z', or '.Z' (indicating a gzip compressed file) are ignored for assigning
5206 * an input file to a reader.
5207 * \n
5208 * It is not possible to hook up a (single) file reader with more than one file extension.
5209 * It is, however, not necessary to implement the same (parsing/writing) methods more than once, if you want to
5210 * support several file extension with the same parser. To do so look at the files reader_lp.c
5211 * and reader_rlp.c. Both support the LP format.
5212 *
5213 *
5214 * @section READER_DATA File Reader Data
5215 *
5216 * Below the header "Data structures" you can find a struct which is called "struct SCIP_ReaderData".
5217 * In this data structure, you can store the data of your file reader. For example, you should store the adjustable
5218 * parameters of the file reader in this data structure.
5219 * If you are using C++, you can add file reader data as usual as object variables to your class.
5220 * \n
5221 * Defining file reader data is optional. You can leave the struct empty.
5222 *
5223 *
5224 * @section READER_INTERFACE Interface Methods
5225 *
5226 * At the bottom of "reader_myreader.c", you can find the interface method SCIPincludeReaderMyreader(),
5227 * which also appears in "reader_myreader.h".
5228 * SCIPincludeReaderMyreader() is called by the user, if (s)he wants to include the reader,
5229 * i.e., if (s)he wants to use the reader in his/her application.
5230 *
5231 * This method only has to be adjusted slightly.
5232 * It is responsible for notifying SCIP of the presence of the reader. For this, you can either call
5233 * SCIPincludeReader(),
5234 * or SCIPincludeReaderBasic() since SCIP version 3.0. In the latter variant, \ref READER_ADDITIONALCALLBACKS "additional callbacks"
5235 * must be added via setter functions as, e.g., SCIPsetReaderCopy(). We recommend this latter variant because
5236 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
5237 * variant must be manually adjusted with every SCIP release containing new callbacks for readers in order to compile.
5238 *
5239 * If you are using file reader data, you have to allocate the memory for the data at this point.
5240 * You can do this by calling:
5241 * \code
5242 * SCIP_CALL( SCIPallocBlockMemory(scip, &readerdata) );
5243 * \endcode
5244 * You also have to initialize the fields in struct SCIP_ReaderData afterwards.
5245 *
5246 * You may also add user parameters for your file reader, see the method SCIPincludeReaderLp() in
5247 * src/scip/reader_lp.c for an example.
5248 *
5249 *
5250 * @section READER_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a File Reader
5251 *
5252 * File reader plugins have no fundamental callback methods. This is due to
5253 * the fact that a file reader can be used for reading and/or writing a
5254 * file. A file reader is only useful if the reader method \ref READERREAD
5255 * and/or the writing method \ref READERWRITE is implemented. One of these
5256 * methods should be implemented for every file reader; the other callback
5257 * methods \ref READERCOPY and \ref READERFREE are optional. In the C++ wrapper class scip::ObjReader, the
5258 * scip_read() and scip_write() methods (which corresponds to the \ref
5259 * READERREAD and \ref READERWRITE callback) are virtual member
5260 * functions. At least one of them should be implemented.
5261 *
5262 * Additional documentation for the callback methods can be found in type_reader.h.
5263 *
5264 *
5265 * @section READER_ADDITIONALCALLBACKS Additional Callback Methods of a File Reader
5266 *
5267 * Additional callbacks can either be passed directly with SCIPincludeReader() to SCIP or via specific
5268 * <b>setter functions</b> after a call of SCIPincludeReaderBasic(), see also @ref READER_INTERFACE.
5269 *
5270 *
5271 * File reader plugins contain only additional callback methods, namely the methods \ref READERREAD,
5272 * \ref READERWRITE, \ref READERFREE, and \ref READERCOPY. Therefore, these are not needed to be implemented. However,
5273 * at least \ref READERREAD and/or \ref READERWRITE should be implemented (see notes
5274 * \ref READER_FUNDAMENTALCALLBACKS "above").
5275 *
5276 *
5277 * @subsection READERREAD
5278 *
5279 * The READERREAD callback is called when the user invokes SCIP to read in a file with file name extension
5280 * corresponding to the READER_EXTENSION property of the file reader. This is usually triggered by a call to the method
5281 * SCIPreadProb() or by an interactive shell command.
5282 * The READERREAD callback should parse the input file and perform the desired action, which usually means
5283 * generating a constraint integer programming model, adding a primal solution, fixing variables
5284 * in an existing model.
5285 * \n
5286 * Typical methods called by a file reader that is used to read/generate constraint
5287 * integer programming models are, for example,
5288 *
5289 * - creating an empty problem: SCIPcreateProb()
5290 * - creating the variables: SCIPcreateVar(), SCIPchgVarType(), SCIPchgVarLb(), SCIPchgVarUb(), SCIPaddVar(), and
5291 * SCIPreleaseVar()
5292 * - modifying the objective function: SCIPchgVarObj() and SCIPsetObjsense().
5293 * - creating the constraints: SCIPcreateConsLinear(), SCIPaddCoefLinear(), SCIPchgLhsLinear(), SCIPchgRhsLinear(),
5294 * SCIPaddCons(), and SCIPreleaseCons()
5295 *
5296 * Primal solutions can only be created for the transformed problem. Therefore, the user has to call SCIPtransformProb()
5297 * before (s)he reads in the file containing the solution and adds it to the solution pool via the method SCIPreadSol().
5298 *
5299 *
5300 * @subsection READERWRITE
5301 *
5302 * The READERWRITE callback is called when the user invokes SCIP to write a problem (original or transformed)
5303 * in the format the reader supports. This is only possible if this callback is implemented. To write the problem
5304 * all necessary information is given through the parameters of this callback method (see type_reader.h). This
5305 * information should be used to output the problem in the requested format. This callback method is usually
5306 * triggered by the call of the methods SCIPwriteOrigProblem(), SCIPwriteTransProblem(), SCIPprintOrigProblem(),
5307 * or SCIPprintTransProblem().
5308 * \n
5309 * A typical method called by a file reader which is used to write/export a constraint
5310 * integer programming model is SCIPinfoMessage(). This method outputs a given string into a file
5311 * or into stdout.
5312 * \n
5313 * For an example we refer to the writing method of the MPS reader (see reader_mps.c).
5314 *
5315 *
5316 * @subsection READERCOPY
5317 *
5318 * The READERCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
5319 * callback as <code>NULL</code> the user disables the execution of the specified reader for all copied SCIP
5320 * instances. The question might arise why to copy that plugin. In case of debugging it is nice to be able to
5321 * write/display the copied instances. Since the reader is in charge of that, you might want to copy the plugin. Below
5322 * you see a standard implementation.
5323 *
5324 * @refsnippet{src/scip/reader_mps.c,SnippetReaderCopyMps}
5325 *
5326 * @subsection READERFREE
5327 *
5328 * If you are using file reader data, you have to implement this method in order to free the file reader data.
5329 * This can be done by the following procedure:
5330 *
5331 * @refsnippet{src/scip/reader_mps.c,SnippetReaderFreeMps}
5332 *
5333 * If you have allocated memory for fields in your file reader data, remember to free this memory
5334 * before freeing the file reader data itself.
5335 * If you are using the C++ wrapper class, this method is not available.
5336 * Instead, just use the destructor of your class to free the member variables of your class.
5337 *
5338 */
5339
5340/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5341
5342/**@page DIALOG How to add dialogs
5343 *
5344 * SCIP comes with a command line shell which allows the user to read in problem instances, modify the solver's
5345 * parameters, initiate the optimization and display certain statistics and solution information. This shell consists
5346 * of dialogs, which are organized as a tree in SCIP. A node of this tree which is not a leaf represents a menu in
5347 * the shell and the children of this node correspond to the entries of this menu (which can again be menus). All
5348 * different dialogs are managed by a dialog handler, which, in particular, is responsible for executing the dialog
5349 * corresponding to the user's command in the shell. The concept of a dialog handler is different to that
5350 * of a constraint handler, which is used to manage objects of the same structure, see \ref CONS. In particular, SCIP
5351 * features only one dialog handler (dialog_default.h), whereas there may exist different constraint handlers.
5352 * \n
5353 * A complete list of all dialogs contained in this release can be found \ref DIALOGS "here".
5354 *
5355 * We now explain how users can extend the interactive shell by adding their own dialog.
5356 * We give the explanation for creating your own source file for each additional dialog. Of course, you can collect
5357 * different dialogs in one source file. Take src/scip/dialog_default.c, where all default dialog plugins are collected, as an
5358 * example.
5359 * As all other default plugins, the default dialog plugin and the template dialog are written in C. C++ users can easily
5360 * adapt the code by using the scip::ObjDialog wrapper base class and implement the scip_...() virtual methods instead of the
5361 * SCIP_DECL_DIALOG... callback methods.
5362 *
5363 * Additional documentation for the callback methods of a dialog can be found in the file type_dialog.h.
5364 *
5365 * Here is what you have to do to add a dialog (assuming your dialog is named "mydialog"):
5366 * -# Copy the template files src/scip/dialog_xyz.c and src/scip/dialog_xyz.h into files named "dialog_mydialog.c"
5367 * and "dialog_mydialog.h".
5368 * \n
5369 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5370 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5371 * -# Use `SCIPincludeDialogMydialog()` in order to include the dialog handler into your SCIP instance,
5372 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5373 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5374 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mydialog".
5375 * -# Adjust the \ref DIALOG_PROPERTIES "properties of the dialog".
5376 * -# Define the \ref DIALOG_DATA "dialog data". This is optional.
5377 * -# Implement the \ref DIALOG_INTERFACE "interface methods".
5378 * -# Implement the \ref DIALOG_FUNDAMENTALCALLBACKS "fundamental callback methods".
5379 * -# Implement the \ref DIALOG_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5380 *
5381 *
5382 * @section DIALOG_PROPERTIES Properties of a Dialog
5383 *
5384 * At the top of the new file "dialog_mydialog.c" you can find the dialog properties.
5385 * These are given as compiler defines.
5386 * In the C++ wrapper class, you have to provide the dialog properties by calling the constructor
5387 * of the abstract base class scip::ObjDialog from within your constructor.
5388 * The properties you have to set have the following meaning:
5389 *
5390 * \par DIALOG_NAME: the name of the dialog.
5391 * In the interactive shell, this name appears as the command name of the dialog in the parent dialog.
5392 * Additionally, if you are searching an entry in a menu with SCIPdialogFindEntry(), this name is looked up.
5393 * Names within one menu have to be unique: no two dialogs in the same menu may have the same name.
5394 *
5395 * \par DIALOG_DESC: the description of the dialog.
5396 * This string is printed as a description of the dialog in the interactive shell if the additional
5397 * callback method \ref DIALOGDESC is not implemented.
5398 *
5399 * \par DIALOG_ISSUBMENU: whether the dialog is a (sub)menu.
5400 * This parameter states whether the dialog is a menu in the interactive shell, i.e., is the parent of further
5401 * dialogs.
5402 *
5403 *
5404 * @section DIALOG_DATA Dialog Data
5405 *
5406 * Below the header "Data structures" you can find a struct which is called "struct SCIP_DialogData".
5407 * In this data structure, you can store the data of your dialog.
5408 * If you are using C++, you can add dialog data as usual as object variables to your class.
5409 * \n
5410 * Defining dialog data is optional. You can leave the struct empty.
5411 *
5412 *
5413 * @section DIALOG_INTERFACE Interface Methods
5414 *
5415 * At the bottom of "dialog_mydialog.c" you can find the interface method SCIPincludeDialogMydialog(), which also appears
5416 * in "dialog_mydialog.h".
5417 * \n
5418 * This method only has to be adjusted slightly.
5419 * It is responsible for notifying SCIP of the presence of the dialog, which can be done by the following lines of code:
5420 *
5421 * @refsnippet{src/scip/dialog_xyz.c,SnippetDialogAddXyz}
5422 *
5423 * Here "parentdialog" has to be an existing dialog which is defined to be a menu (see DIALOG_ISSUBMENU), e.g.,
5424 * the default root dialog. The method SCIPgetRootDialog() returns the root dialog.
5425 *
5426 * 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
5427 * his/her application.
5428 * Note that in order to be able to link the new dialog to an existing default dialog
5429 * (except the root dialog) it has to be included <b>after the
5430 * default dialogs plugin</b>, i.e., the SCIPincludeDialogMydialog() call has to occur after the
5431 * SCIPincludeDialogDefault() call. The SCIPincludeDialogDefault() method is called from within the SCIPincludeDefaultPlugins()
5432 * method. Therefore, it suffices to include your dialog plugins after you have called SCIPincludeDefaultPlugins().
5433 * In case you want to add a dialog to the <b>root dialog</b>, you just use the following
5434 * lines of code to get/create the root dialog.
5435 *
5436 * @refsnippet{tests/src/misc/snippets.c,SnippetDialogCreate}
5437 *
5438 * Therefore, in this case you do not have to worry about the calls of
5439 * SCIPincludeDialogDefault() and SCIPincludeDefaultPlugins() .
5440 *
5441 * If you are using dialog data, you have to allocate the memory for the data at this point.
5442 * You can do this by calling:
5443 * \code
5444 * SCIP_CALL( SCIPallocBlockMemory(scip, &dialogdata) );
5445 * \endcode
5446 * You also have to initialize the fields in struct SCIP_DialogData afterwards.
5447 *
5448 * Consider the following example. The user wants to add a "drawgraph" command to the root menu of SCIP.
5449 * (S)he copies the "dialog_xyz.c" and "dialog_xyz.h" files into files "dialog_drawgraph.c" and "dialog_drawgraph.h", respectively.
5450 * Then, (s)he puts the following code into the SCIPincludeDialogDrawgraph() method, compare SCIPincludeDialogDefault() in
5451 * src/scip/dialog_default.c:
5452 * @refsnippet{tests/src/misc/snippets.c,SnippetDialogInclude}
5453 *
5454 * Using this code, it is even possible to call SCIPincludeDialogDrawgraph() before including the default dialog plugins,
5455 * and you can also call it multiple times without causing inconsistencies in the dialog structure.
5456 *
5457 *
5458 * @section DIALOG_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Dialog
5459 *
5460 * Dialogs have only one fundamental callback method, namely the \ref DIALOGEXEC method.
5461 * This method has to be implemented for every dialog; the other callback methods are optional.
5462 * In the C++ wrapper class scip::ObjDialog, the scip_exec() method (which corresponds to the \ref DIALOGEXEC callback) is a virtual
5463 * abstract member function.
5464 * You have to implement it in order to be able to construct an object of your dialog class.
5465 *
5466 * Additional documentation for the callback methods can be found in type_dialog.h.
5467 *
5468 * @subsection DIALOGEXEC
5469 *
5470 * The DIALOGEXEC method is invoked, if the user selected the dialog's command name in the parent's menu. It should
5471 * execute what is stated in DIALOG_DESC, e.g., the display constraint handlers dialog should display information about
5472 * the constraint handlers included in SCIP, see src/scip/dialog_default.c.
5473 *
5474 * For typical methods called by the execution method, have a look at src/scip/dialog_default.c.
5475 *
5476 * The callback has to return which dialog should be processed next. This can be, for example, the root dialog
5477 * (SCIPdialoghdlrGetRoot()), the parent dialog (SCIPdialogGetParent()) or NULL, which stands for closing the interactive
5478 * shell.
5479 *
5480 *
5481 * @section DIALOG_ADDITIONALCALLBACKS Additional Callback Methods of a Dialog
5482 *
5483 * The additional callback methods do not need to be implemented in every case.
5484 * They can be used, for example, to free private data.
5485 *
5486 * @subsection DIALOGFREE
5487 *
5488 * If you are using dialog data, you have to implement this method in order to free the dialog data.
5489 * This can be done by the following procedure:
5490 * @refsnippet{tests/src/misc/snippets.c,SnippetDialogFree}
5491 *
5492 * If you have allocated memory for fields in your dialog data, remember to free this memory
5493 * before freeing the dialog data itself.
5494 * If you are using the C++ wrapper class, this method is not available.
5495 * Instead, just use the destructor of your class to free the member variables of your class.
5496 *
5497 * @subsection DIALOGDESC
5498 *
5499 * This method is called when the help menu of the parent is displayed. It should output (usually a single line of)
5500 * information describing the meaning of the dialog.
5501 * \n
5502 * If this callback is not implemented, the description string of the dialog (DIALOG_DESC) is displayed instead.
5503 *
5504 * @subsection DIALOGCOPY
5505 *
5506 * The DIALOGCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
5507 * callback as <code>NULL</code> the user disables the execution of this dialog for all copied SCIP instances. In
5508 * general there is no need to copy any dialog since it is most unlikely to start the interactive shell of the copied
5509 * instances.
5510 *
5511 */
5512
5513/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5514
5515/**@page DISP How to add display columns
5516 *
5517 * While solving a constraint integer program, SCIP displays status information in a column-like fashion. The current
5518 * number of processed branching tree nodes, the solving time, and the relative gap between primal and dual bound are
5519 * examples of such display columns. There already exists a wide variety of display columns which can be activated or
5520 * deactivated on demand, see src/scip/disp_default.c. Additionally, the user can implement his/her own display columns
5521 * in order to track problem or algorithm specific values.
5522 * \n
5523 * A complete list of all displays contained in this release can be found \ref DISPLAYS "here".
5524 *
5525 * We now explain how users can add their own display columns.
5526 * We give the explanation for creating your own source file for each additional display column. Of course, you can collect
5527 * different additional display columns in one source file.
5528 * Take src/scip/disp_default.c, where all default display columns are collected, as an example.
5529 * As all other default plugins, the default display column plugins and the display column template are written in C.
5530 * C++ users can easily adapt the code by using the scip::ObjDisp wrapper base class and implement the scip_...() virtual methods
5531 * instead of the SCIP_DECL_DISP... callback methods.
5532 *
5533 *
5534 * Additional documentation for the callback methods of a display column can be found in the file type_disp.h.
5535 *
5536 * Here is what you have to do to implement a display column (assuming your display column is named "mydisplaycolumn"):
5537 * -# Copy the template files src/scip/disp_xyz.c and src/scip/disp_xyz.h into files named "disp_mydisplaycolumn.c"
5538 * and "disp_mydisplaycolumn.h".
5539 \n
5540 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5541 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5542 * -# Use `SCIPincludeDispMydisplaycolumn()` in order to include the display column into your SCIP instance,
5543 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5544 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5545 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mydisplaycolumn".
5546 * -# Adjust the \ref DISP_PROPERTIES "properties of the display column".
5547 * -# Define the \ref DISP_DATA "display column data". This is optional.
5548 * -# Implement the \ref DISP_INTERFACE "interface methods".
5549 * -# Implement the \ref DISP_FUNDAMENTALCALLBACKS "fundamental callback methods".
5550 * -# Implement the \ref DISP_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5551 *
5552 *
5553 * @section DISP_PROPERTIES Properties of a Display Column
5554 *
5555 * At the top of the new file "disp_mydisplaycolumn.c" you can find the display column properties.
5556 * These are given as compiler defines.
5557 * In the C++ wrapper class, you have to provide the display column properties by calling the constructor
5558 * of the abstract base class scip::ObjDisp from within your constructor.
5559 * The properties you have to set have the following meaning:
5560 *
5561 * \par DISP_NAME: the name of the display column.
5562 * This name is used in the interactive shell to address the display column.
5563 * Additionally, if you are searching for a display column with SCIPfindDisp(), this name is looked up.
5564 * Names have to be unique: no two display columns may have the same name.
5565 *
5566 * \par DISP_DESC: the description of the display column.
5567 * This string is printed as a description of the display column in the interactive shell.
5568 *
5569 * \par DISP_HEADER: the header of the display column.
5570 * This string is printed as the header of the display column in the status information display.
5571 *
5572 * \par DISP_WIDTH: the width of the display column.
5573 * This parameter defines the width (number of characters) of the display column. The value of the parameter has to be
5574 * greater than or equal to the number of characters in the header string.
5575 *
5576 * \par DISP_PRIORITY: the priority of the display column.
5577 * The total width of status information lines is bounded by the parameter "display width". The display columns actually contained
5578 * in the status information display are selected in decreasing order of their priority. Furthermore, the user can force
5579 * columns to be displayed or not to be displayed in the status information display. For that, (s)he has to switch the value
5580 * of the display column's parameter "active" from "auto" (its default value) to "on" or "off", respectively.
5581 *
5582 * \par DISP_POSITION: the relative position of the display column.
5583 * In the status information display, the display columns are arranged from left to right in increasing order of their
5584 * relative position.
5585 *
5586 * \par DISP_STRIPLINE: the default for whether the display column should be separated with a line from its right neighbor.
5587 * This parameter states whether the display column should be separated with the string "|" from its right neighbor. In so
5588 * doing, the clearness of the status information display may improve.
5589 *
5590 * @section DISP_DATA Display Column Data
5591 *
5592 * Below the header "Data structures" you can find a struct which is called "struct SCIP_DispData".
5593 * In this data structure, you can store the data of your display column. For example, you should store the adjustable
5594 * parameters of the display column in this data structure.
5595 * If you are using C++, you can add display column data as usual as object variables to your class.
5596 * \n
5597 * Defining display column data is optional. You can leave the struct empty.
5598 *
5599 *
5600 * @section DISP_INTERFACE Interface Methods
5601 *
5602 * At the bottom of "disp_mydisplaycolumn.c" you can find the interface method SCIPincludeDispMydisplaycolumn(), which also
5603 * appears in "disp_mydisplaycolumn.h".
5604 * \n
5605 * This method only has to be adjusted slightly.
5606 * It is responsible for notifying SCIP of the presence of the display column by calling the method
5607 * SCIPincludeDisp().
5608 *
5609 * 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
5610 * application.
5611 *
5612 * If you are using display column data, you have to allocate the memory for the data at this point.
5613 * You can do this by calling:
5614 * \code
5615 * SCIP_CALL( SCIPallocBlockMemory(scip, &dispdata) );
5616 * \endcode
5617 * You also have to initialize the fields in struct SCIP_DispData afterwards.
5618 *
5619 * Although this is very uncommon, you may also add user parameters for your display column, see the method
5620 * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
5621 *
5622 *
5623 * @section DISP_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Display Column
5624 *
5625 * Display column plugins have only one fundamental callback method, namely the \ref DISPOUTPUT method.
5626 * This method has to be implemented for every display column; the other callback methods are optional.
5627 * In the C++ wrapper class scip::ObjDisp, the scip_output() method (which corresponds to the \ref DISPOUTPUT callback) is a virtual
5628 * abstract member function.
5629 * You have to implement it in order to be able to construct an object of your display column class.
5630 *
5631 * Additional documentation for the callback methods can be found in type_disp.h.
5632 *
5633 * @subsection DISPOUTPUT
5634 *
5635 * The DISPOUTPUT callback is called after each pricing loop during node processing and after a node has been processed.
5636 * In addition, at the root node, the callback is executed after each iteration of the price-and-cut loop.
5637 * It should write the display column information for the current node to a given output file stream.
5638 *
5639 * Typical methods called by a display column are, for example, SCIPdispLongint(), SCIPdispInt(), SCIPdispTime(), and
5640 * SCIPinfoMessage().
5641 *
5642 *
5643 * @section DISP_ADDITIONALCALLBACKS Additional Callback Methods of a Display Column
5644 *
5645 * The additional callback methods do not need to be implemented in every case.
5646 * They can be used, for example, to initialize and free private data.
5647 *
5648 * @subsection DISPCOPY
5649 *
5650 * The DISPCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this callback
5651 * as <code>NULL</code> the user disables the execution of the specified column. In general it is probably not needed to
5652 * implement that callback since the output of the copied instance is usually suppressed. In the other case or for
5653 * debugging the callback should be implement.
5654 *
5655 *
5656 * @subsection DISPFREE
5657 *
5658 * If you are using display column data, you have to implement this method in order to free the display column data.
5659 * This can be done by the following procedure:
5660 * @refsnippet{tests/src/misc/snippets.c,SnippetDispFree}
5661 *
5662 * If you have allocated memory for fields in your display column data, remember to free this memory
5663 * before freeing the display column data itself.
5664 * If you are using the C++ wrapper class, this method is not available.
5665 * Instead, just use the destructor of your class to free the member variables of your class.
5666 *
5667 * @subsection DISPINIT
5668 *
5669 * The DISPINIT callback is executed after the problem is transformed.
5670 * The display column may, e.g., use this call to initialize its display column data.
5671 *
5672 * @subsection DISPEXIT
5673 *
5674 * The DISPEXIT callback is executed before the transformed problem is freed.
5675 * In this method, the display column should free all resources that have been allocated for the solving process in
5676 * \ref DISPINIT.
5677 *
5678 * @subsection DISPINITSOL
5679 *
5680 * The DISPINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
5681 * begin. The display column may use this call to initialize its branch-and-bound specific data.
5682 *
5683 * @subsection DISPEXITSOL
5684 *
5685 * The DISPEXITSOL callback is executed before the branch-and-bound process is freed. The display column should use this
5686 * call to clean up its branch-and-bound specific data.
5687 */
5688
5689/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5690
5691/**@page EVENT How to add event handler
5692 *
5693 * While solving a constraint integer program, SCIP drops thousands of events such as SCIP_EVENTTYPE_VARFIXED (a
5694 * complete list of all events is given in type_event.h). These events can be caught and used to do something after a
5695 * certain event happens. Events can be used to speed up the solution process. For example, the set partitioning
5696 * constraint is only worth propagating if one of the involved variables is fixed. This can be detected by
5697 * catching the event SCIP_EVENTTYPE_VARFIXED. To be able to catch an event it is necessary to write an event handler
5698 * which defines what to do after a certain event was caught.
5699 *
5700 * We now explain how users can add their own event handlers. We give the explanation for creating your own
5701 * source file for each additional event handler. Of course, you can collect different event handlers in one source file
5702 * or you can put the event handler directly into the constraint handler. In a \ref EVENTUSAGE "second step" we discuss
5703 * the usage of an event handler. This means how to catch and drop events. \ref EVENTTYPES "Finally", we give some notes on the existing
5704 * types of events.
5705 *
5706 * Take src/scip/cons_logior.c, where the event handler is directly included into the constraint handler. As all other
5707 * default plugins, the event handlers are written in C. C++ users can easily adapt the code by using the scip::ObjEventhdlr
5708 * wrapper base class and implement the scip_...() virtual methods instead of the SCIP_DECL_EVENT... callback methods.
5709 *
5710 * Additional documentation for the callback methods of an event handler can be found in the file type_event.h. There is
5711 * also an example written in C which deals with an event handler. You find this example in the directory
5712 * "examples/Eventhdlr/". An C++ example can be found within the TSP project (examples/TSP/src/EventhdlrNewSol.cpp).
5713 *
5714 * Here is what you have to do to implement an event handler (assuming your event handler is named "bestsol"):
5715 * -# Copy the template files src/scip/event_xyz.c and src/scip/event_xyz.h into files named "event_bestsol.c"
5716 * and "event_bestsol.h".
5717 \n
5718 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5719 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5720 * -# Use `SCIPincludeEventBestsol()` in order to include the event handler into your SCIP instance,
5721 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5722 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5723 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "bestsol".
5724 * -# Adjust the \ref EVENTHDLR_PROPERTIES "properties of the event handler".
5725 * -# Implement the \ref EVENT_INTERFACE "interface methods".
5726 * -# Implement the \ref EVENT_FUNDAMENTALCALLBACKS "fundamental callback methods".
5727 * -# Implement the \ref EVENT_ADDITIONALCALLBACKS "additional callback methods". This is optional.
5728 *
5729 *
5730 * @section EVENTHDLR_PROPERTIES Properties of a Event Handler
5731 *
5732 * At the top of the new file "event_bestsol.c" you can find the event handler properties.
5733 * These are given as compiler defines.
5734 * In the C++ wrapper class, you have to provide the event handler properties by calling the constructor
5735 * of the abstract base class scip::ObjEventhdlr from within your constructor.
5736 * The properties you have to set have the following meaning:
5737 *
5738 * \par EVENT_NAME: the name of the event handler.
5739 * This name has to be unique with respect to all other event handlers. If you are searching for an event handler with
5740 * SCIPfindEventhdlr(), this name is looked up.
5741 *
5742 * \par EVENT_DESC: the description of the event handler.
5743 * This string is printed as a description of the event handler.
5744 *
5745 * @section EVENTHDLR_DATA Event Handler Data
5746 *
5747 * Below the header "Data structures" you can find a struct which is called "struct SCIP_EventhdlrData".
5748 * In this data structure, you can store the data of your event handler. For example, you should store the adjustable
5749 * parameters of the event handler in this data structure.
5750 * If you are using C++, you can add event handler data as usual as object variables to your class.
5751 * \n
5752 * Defining event handler data is optional. You can leave the struct empty.
5753 *
5754 *
5755 * @section EVENT_INTERFACE Interface Methods
5756 *
5757 * At the bottom of "event_bestsol.c", you can find the interface method SCIPincludeEventBestsol(),
5758 * which also appears in "event_bestsol.h".
5759 * SCIPincludeEventBestsol() is called by the user, if (s)he wants to include the event handler,
5760 * i.e., if (s)he wants to use the event handler in his/her application.
5761 *
5762 * This method only has to be adjusted slightly.
5763 * It is responsible for notifying SCIP of the presence of the event handler. For this, you can either call
5764 * SCIPincludeEventhdlr(),
5765 * or SCIPincludeEventhdlrBasic() since SCIP version 3.0. In the latter variant, \ref EVENT_ADDITIONALCALLBACKS "additional callbacks"
5766 * must be added via setter functions as, e.g., SCIPsetReaderCopy(). We recommend this latter variant because
5767 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
5768 * variant must be manually adjusted with every SCIP release containing new callbacks for event handlers in order to compile.
5769 *
5770 * If you are using event handler data, you have to allocate the memory for the data at this point.
5771 * You can do this by calling:
5772 * \code
5773 * SCIP_CALL( SCIPallocBlockMemory(scip, &eventhdlrdata) );
5774 * \endcode
5775 * You also have to initialize the fields in struct SCIP_EventhdlrData afterwards.
5776 *
5777 * Although this is very uncommon, you may also add user parameters for your event handler, see the method
5778 * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
5779 *
5780 *
5781 * @section EVENT_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Event Handler
5782 *
5783 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
5784 * an operational algorithm.
5785 * They are passed together with the event handler itself to SCIP using SCIPincludeEventhdlr() or SCIPincludeEventhdlrBasic(),
5786 * see @ref EVENT_INTERFACE.
5787 *
5788 *
5789 * Event handler plugins have only one fundamental callback method, namely the \ref EVENTEXEC method. This method has
5790 * to be implemented for every event handler; the other callback methods are optional. In the C++ wrapper class
5791 * scip::ObjEventhdlr, the scip_exec() method (which corresponds to the \ref EVENTEXEC callback) is a virtual abstract member
5792 * function. You have to implement it in order to be able to construct an object of your event handler class.
5793 *
5794 * Additional documentation for the callback methods can be found in type_event.h.
5795 *
5796 * @subsection EVENTEXEC
5797 *
5798 * The EVENTEXEC callback is called after the requested event happened. Then the event handler can do some action in
5799 * reaction to the event.
5800 *
5801 * Typical the execution method sets a parameter to TRUE to indicate later in solving process that something happened
5802 * which should be analyzed further. In the \ref cons_knapsack.h "knapsack constraint handler" you find such a typical
5803 * example.
5804 *
5805 * @section EVENT_ADDITIONALCALLBACKS Additional Callback Methods of a Event Handler
5806 *
5807 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
5808 * implemented for most applications, they can be used, for example, to initialize and free private data.
5809 * Additional callbacks can either be passed directly with SCIPincludeEventhdlr() to SCIP or via specific
5810 * <b>setter functions</b> after a call of SCIPincludeEventhdlrBasic(), see also @ref EVENT_INTERFACE.
5811 *
5812 * @subsection EVENTCOPY
5813 *
5814 * The EVENTCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
5815 * callback as <code>NULL</code> the user disables the execution of the specified event handler for all copied SCIP
5816 * instances. Note that in most cases the event handler in the copied instance will be initialize by those objects (such
5817 * as constraint handlers or propagators) which need this event handler (see \ref cons_knapsack.h). In these cases the copy
5818 * callback can be ignored. In case of general events, such as a new best solution being found
5819 * (SCIP_EVENTTYPE_BESTSOLFOUND), you might want to implement that callback. The event handler example which you find
5820 * in the directory "examples/Eventhdlr/" uses that callback.
5821 *
5822 * @refsnippet{src/scip/event_softtimelimit.c,SnippetEventCopySofttimelimit}
5823 *
5824 * @subsection EVENTFREE
5825 *
5826 * If you are using event handler data, you have to implement this method in order to free the event handler data.
5827 * This can be done by the following procedure:
5828 *
5829 * @refsnippet{src/scip/event_softtimelimit.c,SnippetEventFreeSofttimelimit}
5830 *
5831 * If you have allocated memory for fields in your event handler data, remember to free this memory
5832 * before freeing the event handler data itself.
5833 * If you are using the C++ wrapper class, this method is not available.
5834 * Instead, just use the destructor of your class to free the member variables of your class.
5835 *
5836 *
5837 * @subsection EVENTINIT
5838 *
5839 * The EVENTINIT callback is executed after the problem is transformed.
5840 * The event handler may, e.g., use this call to initialize its event handler data.
5841 *
5842 * @subsection EVENTEXIT
5843 *
5844 * The EVENTEXIT callback is executed before the transformed problem is freed.
5845 * In this method, the event handler should free all resources that have been allocated for the solving process in
5846 * \ref EVENTINIT.
5847 *
5848 * @subsection EVENTINITSOL
5849 *
5850 * The EVENTINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
5851 * begin. The event handler may use this call to initialize its branch-and-bound specific data.
5852 *
5853 * @subsection EVENTEXITSOL
5854 *
5855 * The EVENTEXITSOL callback is executed before the branch-and-bound process is freed. The event handler should use this
5856 * call to clean up its branch-and-bound specific data.
5857 *
5858 * @section EVENTUSAGE Catching and Dropping Events
5859 *
5860 * After you have implemented the event handler, you have to tell SCIP for which events this event handler should be
5861 * used. This can be a general events, such as <code>SCIP_EVENTTYPE_BESTSOLFOUND</code>, or a variable event which is the most common
5862 * way.
5863 *
5864 * In case of a general (not variable) event you use the function SCIPcatchEvent() to attach to an event and
5865 * SCIPdropEvent() to release this event later.
5866 *
5867 * \code
5868 * SCIP_CALL( SCIPcatchEvent( scip, SCIP_EVENTTYPE_BESTSOLFOUND, eventhdlr, NULL, NULL) );
5869 * \endcode
5870 *
5871 * \code
5872 * SCIP_CALL( SCIPdropEvent( scip, SCIP_EVENTTYPE_BESTSOLFOUND, eventhdlr, NULL, NULL) );
5873 * \endcode
5874 *
5875 * If you want trigger some variable event, you use the method SCIPcatchVarEvent() to attach the variable event and
5876 * SCIPdropVarEvent() to drop it later.
5877 *
5878 * \code
5879 * SCIP_CALL( SCIPcatchVarEvent( scip, var, SCIP_EVENTTYPE_VARFIXED, eventhdlr, NULL, NULL) );
5880 * \endcode
5881 *
5882 * \code
5883 * SCIP_CALL( SCIPdropVarEvent( scip, var, SCIP_EVENTTYPE_VARFIXED, eventhdlr, NULL, NULL) );
5884 * \endcode
5885 *
5886 * @section EVENTTYPES Event types
5887 *
5888 * All available events are listed in type_event.h. There are atomic events such as <code>SCIP_EVENTTYPE_VARFIXED</code>
5889 * and combined events such as <code>SCIP_EVENTTYPE_VARCHANGED</code>. The events are encoded via bit masks. Each atomic
5890 * event has a unique power of two. This enables combination of the atomic events.
5891 *
5892 * SCIP only throws atomic events. However, an event handler might be interested in bunch of events. Through the
5893 * underlying bit masks it is possible to combine the atomic events. For example, <code>SCIP_EVENTTYPE_VARCHANGED</code>
5894 * is an event which combines the events <code>SCIP_EVENTTYPE_VARFIXED</code>, <code>SCIP_EVENTTYPE_VARUNLOCKED</code>,
5895 * <code>SCIP_EVENTTYPE_OBJCHANGED</code>, <code>SCIP_EVENTTYPE_GBDCHANGED</code>,
5896 * <code>SCIP_EVENTTYPE_DOMCHANGED</code>, and <code>SCIP_EVENTTYPE_IMPLADDED</code>.
5897 *
5898 * \code
5899 * #define SCIP_EVENTTYPE_VARCHANGED (SCIP_EVENTTYPE_VARFIXED | SCIP_EVENTTYPE_VARUNLOCKED | SCIP_EVENTTYPE_OBJCHANGED
5900 * | SCIP_EVENTTYPE_GBDCHANGED | SCIP_EVENTTYPE_DOMCHANGED | SCIP_EVENTTYPE_IMPLADDED)
5901 * \endcode
5902 *
5903 * Depending on the event type, the event offers different information. The methods which can be used to gain
5904 * access to this information are given in pub_event.h.
5905 *
5906 */
5907
5908/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5909
5910/**@page NLPI How to add interfaces to nonlinear programming solvers
5911 *
5912 * NLPIs are used to interface a solver for nonlinear programs (NLP).
5913 * It is used, e.g., to solve convex relaxations of the problem or to find locally optimal solutions of
5914 * nonlinear relaxations or subproblems.
5915 * The NLPI has been designed such that it can be used independently of a SCIP problem.
5916 *
5917 * While the NLPI itself corresponds to the solver interface, the NLPIPROBLEM corresponds to the
5918 * (solver specific) representation of a concrete nonlinear program.
5919 * An NLP is specified as a set of indexed variables with variable bounds, an objective function,
5920 * and a set of constraints, where each constraint is specified as a function which is restricted to lie
5921 * between given left and right hand sides (possibly infinite).
5922 * A function consists of a linear and a nonlinear part.
5923 * The linear part is specified via variable indices and coefficients, while the nonlinear part is specified via an expression.
5924 * That is, the user of the NLPI does not provide function evaluation callbacks but an algebraic representation of the NLP.
5925 * Interfaces for solvers that require function evaluations can make use of the \ref NLPIOracle "NLPIORACLE", which
5926 * provides functionality to store a NLP and compute functions values, gradients, Jacobians, and Hessians.
5927 * See the interface to Ipopt for an example on how to use the NLPIORACLE.
5928 *
5929 * A complete list of all NLPIs contained in this release can be found \ref NLPIS "here".
5930 *
5931 * We now explain how users can add their own NLP solver interface.
5932 * Take the interface to Ipopt (src/scip/nlpi_ipopt.cpp) as an example.
5933 * Unlike most other plugins, it is written in C++.
5934 * Additional documentation for the callback methods of an NLPI, in particular for their input parameters,
5935 * can be found in the file \ref type_nlpi.h.
5936 *
5937 * Here is what you have to do to implement an NLPI:
5938 * -# 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".
5939 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
5940 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
5941 * -# Use `SCIPincludeNlpSolverMysolver()` in order to include the NLPI into your SCIP instance,
5942 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
5943 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
5944 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mysolver".
5945 * -# Adjust the properties of the nlpi (see \ref NLPI_PROPERTIES).
5946 * -# Define the NLPI and NLPIPROBLEM data (see \ref NLPI_DATA).
5947 * -# Implement the interface methods (see \ref NLPI_INTERFACE).
5948 * -# Implement the fundamental callback methods (see \ref NLPI_FUNDAMENTALCALLBACKS).
5949 * -# Implement the additional callback methods (see \ref NLPI_ADDITIONALCALLBACKS). This is optional.
5950 *
5951 *
5952 * @section NLPI_PROPERTIES Properties of an NLPI
5953 *
5954 * At the top of the new file "nlpi_mysolver.c", you can find the NLPI properties.
5955 * These are given as compiler defines.
5956 * The properties you have to set have the following meaning:
5957 *
5958 * \par NLPI_NAME: the name of the NLP solver interface.
5959 * This name is used in the interactive shell to address the NLPI.
5960 * Additionally, if you are searching for an NLPI with SCIPfindNlpi(), this name is looked up.
5961 * Names have to be unique: no two NLPIs may have the same name.
5962 *
5963 * \par NLPI_DESC: the description of the NLPI.
5964 * This string is printed as a description of the NLPI in the interactive shell.
5965 *
5966 * \par NLPI_PRIORITY: the priority of the NLPI.
5967 * If an NLP has to be solved, an NLP solver has to be selected.
5968 * By default, the solver with the NLPI with highest priority is selected.
5969 * The priority of an NLPI should be set according to performance of the solver:
5970 * solvers that provide fast algorithms that are usually successful on a wide range of problems should have a high priority.
5971 * An easy way to list the priorities of all NLPIs is to type "display nlpis" in the interactive shell of SCIP.
5972 *
5973 * @section NLPI_DATA NLPI Data
5974 *
5975 * Below the header "Data structures" you can find structs which are called `struct SCIP_NlpiData` and `struct SCIP_NlpiProblem`.
5976 * In these data structures, you can store the data of your solver interface and of a specific NLP problem.
5977 * For example, you could store a pointer to your NLP solver environment object in the `SCIP_NlpiData` data structure
5978 * and store a pointer to an NLPIORACLE in the `SCIP_NlpiProblem` data structure.
5979 *
5980 * @section NLPI_INTERFACE Interface Methods
5981 *
5982 * At the bottom of "nlpi_mysolver.c", you can find the interface method SCIPincludeNlpSolverXyz(),
5983 * which also appears in "nlpi_mysolver.h".
5984 *
5985 * This method only has to be adjusted slightly.
5986 * It is responsible for creating an NLPI that contains all properties and callback methods of your
5987 * solver interface and included it into SCIP by calling the method SCIPincludeNlpi().
5988 * SCIPincludeNlpSolverXyz() is called by the user (e.g., SCIP), if (s)he wants to use this solver interface in his/her application.
5989 *
5990 * If you are using NLPI data, you have to allocate the memory for the data at this point.
5991 * You can do this by calling:
5992 * \code
5993 * SCIP_CALL( SCIPallocBlockMemory(scip, &nlpidata) );
5994 * \endcode
5995 * You also have to initialize the fields in struct SCIP_NlpiData afterwards. For freeing the
5996 * NLPI data, see \ref NLPIFREE.
5997 *
5998 *
5999 * @section NLPI_FUNDAMENTALCALLBACKS Fundamental Callback Methods of an NLPI
6000 *
6001 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
6002 * an operational algorithm. Most NLPI callbacks are fundamental.
6003 *
6004 * Additional documentation of the callback methods, in particular to their input parameters,
6005 * can be found in \ref type_nlpi.h.
6006 *
6007 * @subsection NLPIFREE
6008 *
6009 * The NLPIFREE callback is executed if the NLP solver interface data structure should be freed, e.g., when a SCIP instance is freed.
6010 *
6011 * @subsection NLPICREATEPROBLEM
6012 *
6013 * The NLPICREATEPROBLEM callback is executed if a particular NLP problem is to be created.
6014 * The callback method should initialize a SCIP_NlpiProblem struct here that corresponds to an empty NLP.
6015 *
6016 * @subsection NLPIFREEPROBLEM
6017 *
6018 * The NLPIFREEPROBLEMPOINTER callback is executed if a particular NLP problem is to be freed.
6019 * The callback method should free a SCIP_NlpiProblem struct here.
6020 *
6021 * @subsection NLPIADDVARS
6022 *
6023 * The NLPIADDVARS callback is executed if a set of variables with lower and upper bounds and names should be added to a particular NLP.
6024 * The callback method must add the new variables behind the previously added variables, if any.
6025 * If NULL is given for the lower bounds arguments, -infinity is assumed as lower bound for each new variable.
6026 * If NULL is given for the upper bounds arguments, +infinity is assumed as upper bound for each new variable.
6027 * It is also permitted to use NULL for the names argument.
6028 *
6029 * @subsection NLPIADDCONSTRAINTS
6030 *
6031 * The NLPIADDCONSTRAINTS callback is executed if a set of constraints should be added to a particular NLP.
6032 * Constraints are specified by providing left- and right-hand-sides, linear coefficients, expressions, and constraint names.
6033 * All of these arguments are optional, giving NULL for left-hand-sides corresponds to -infinity, giving NULL for right-hand-sides corresponds to +infinity.
6034 *
6035 * @subsection NLPISETOBJECTIVE
6036 *
6037 * The NLPISETOBJECTIVE callback is executed to set the objective function of a particular NLP.
6038 *
6039 * @subsection NLPICHGVARBOUNDS
6040 *
6041 * The NLPICHGVARBOUNDS callback is executed to change the bounds on a set of variables of an NLP.
6042 *
6043 * @subsection NLPICHGCONSSIDES
6044 *
6045 * The NLPICHGCONSSIDES callback is executed to change the sides on a set of constraints of an NLP.
6046 *
6047 * @subsection NLPIDELVARSET
6048 *
6049 * The NLPIDELVARSET callback is executed to delete a set of variables from an NLP.
6050 * The caller provides an array in which for each variable it is marked whether it should be deleted.
6051 * In the same array, the method should return the new position of each variable in the NLP, or -1 if it was deleted.
6052 *
6053 * @subsection NLPIDELCONSSET
6054 *
6055 * The NLPIDELCONSSET callback is executed to delete a set of constraints from an NLP.
6056 * The caller provides an array in which for each constraint it is marked whether it should be deleted.
6057 * In the same array, the method should return the new position of each constraint in the NLP, or -1 if it was deleted.
6058 *
6059 * @subsection NLPICHGLINEARCOEFS
6060 *
6061 * The NLPICHGLINEARCOEFS callback is executed to change the coefficients in the linear part of the objective function or a constraint of an NLP.
6062 *
6063 * @subsection NLPICHGEXPR
6064 *
6065 * The NLPICHGEXPR callback is executed to replace the expression of the objective function or a constraint of an NLP.
6066 *
6067 * @subsection NLPICHGOBJCONSTANT
6068 *
6069 * The NLPICHGOBJCONSTANT callback is executed to change the constant offset of the objective function of an NLP.
6070 *
6071 * @subsection NLPISOLVE
6072 *
6073 * The NLPISOLVE callback is executed when an NLP should be solved.
6074 * The solver may use the initial guess provided by \ref NLPISETINITIALGUESS as starting point.
6075 * The status of the solving process and solution can be requested by
6076 * \ref NLPIGETSOLSTAT, \ref NLPIGETTERMSTAT, \ref NLPIGETSOLUTION, and \ref NLPIGETSTATISTICS.
6077 *
6078 * @subsection NLPIGETSOLSTAT
6079 *
6080 * The NLPIGETSOLSTAT callback can be used to request the solution status (solved, infeasible, ...) after an NLP has been solved.
6081 *
6082 * @subsection NLPIGETTERMSTAT
6083 *
6084 * The NLPIGETTERMSTAT callback can be used to request the termination reason (normal, iteration limit, ...) after an NLP has been solved.
6085 *
6086 * @subsection NLPIGETSOLUTION
6087 *
6088 * The NLPIGETSOLUTION callback can be used to request the primal and dual solution values after an NLP solve.
6089 * The method should pass pointers to arrays of variable values to the caller.
6090 * 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.
6091 *
6092 * @subsection NLPIGETSTATISTICS
6093 *
6094 * The NLPIGETSTATISTICS callback can be used to request the statistical values (number of iterations, time, ...) after an NLP solve.
6095 * The method should fill the provided NLPSTATISTICS data structure.
6096 *
6097 * @section NLPI_ADDITIONALCALLBACKS Additional Callback Methods of an NLPI
6098 *
6099 * The additional callback methods do not need to be implemented in every case.
6100 *
6101 * @subsection NLPICOPY
6102 *
6103 * The NLPICOPY callback is executed if the plugin should be copied, e.g., when a SCIP instance is copied.
6104 *
6105 * It is advisable to implement this callback to make the NLP solver available in sub-SCIPs.
6106 * Note that the sub-NLP heuristic solves NLPs in a sub-SCIP.
6107 *
6108 * @subsection NLPIGETSOLVERPOINTER
6109 *
6110 * The NLPIGETSOLVERPOINTER callback can be used to pass a pointer to a solver specific data structure to the user.
6111 * Return NULL if you do not have a pointer to return.
6112 *
6113 * @subsection NLPIGETPROBLEMPOINTER
6114 *
6115 * The NLPIGETPROBLEMPOINTER callback can be used to pass a pointer to a solver specific data structure of the NLP to the user.
6116 *
6117 * @subsection NLPISETINITIALGUESS
6118 *
6119 * The NLPISETINITIALGUESS callback is executed to provide primal and dual initial values for the variables and constraints of an NLP.
6120 * 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.
6121 * 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).
6122 * In this case, the solver should clear previously set starting values and setup its own starting point.
6123 *
6124 */
6125
6126/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6127
6128/**@page EXPRINT How to add interfaces to expression interpreters
6129 *
6130 * An expression interpreter is a tool to compute point-wise the function values, gradients, and
6131 * Hessians of algebraic expressions which are given in the form of an expression.
6132 * Typically, this is done via automatic differentiation.
6133 * It is used, e.g., by an NLP solver interface to compute Jacobians and Hessians for the solver.
6134 *
6135 * The expression interpreter interface in SCIP has been implemented similar to those of the LP solver interface (LPI).
6136 * For one binary, exactly one expression interpreter has to be linked.
6137 * The expression interpreter API has been designed such that it can be used independently from a SCIP problem.
6138 *
6139 * A complete list of all expression interpreters contained in this release can be found \ref EXPRINTS "here".
6140 *
6141 * We now explain how users can add their own expression interpreters.
6142 * Take the interface to CppAD (\ref exprinterpret_cppad.cpp) as an example.
6143 * Unlike most other plugins, it is written in C++.
6144 *
6145 * Additional documentation for the callback methods of an expression interpreter, in particular for their input parameters,
6146 * can be found in the file \ref exprinterpret.h.
6147 *
6148 * Here is what you have to do to implement an expression interpreter:
6149 * -# Copy the file \ref exprinterpret_none.c into a file named "exprinterpret_myad.c".
6150 * Make sure to adjust your build system such that this file is compiled and linked to your project instead of exprinterpret implementations. \n
6151 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6152 * -# Open the new file with a text editor.
6153 * -# Define the expression interpreter data (see \ref EXPRINT_DATA).
6154 * -# Implement the interface methods (see \ref EXPRINT_INTERFACE).
6155 *
6156 *
6157 * @section EXPRINT_DATA Expression Interpreter Data
6158 *
6159 * In `struct SCIP_ExprInt`, you can store the general data of your expression interpreter.
6160 * For example, you could store the environment of your automatic differentiation code.
6161 *
6162 * @section EXPRINT_INTERFACE Interface Methods
6163 *
6164 * The expression interpreter has to implement a set of interface method.
6165 * In your "exprinterpret_myad.c", these methods are mostly dummy methods that return error codes.
6166 *
6167 * @subsection SCIPexprintGetName
6168 *
6169 * The SCIPexprintGetName() method should return the name of the expression interpreter.
6170 *
6171 * @subsection SCIPexprintGetDesc
6172 *
6173 * The SCIPexprintGetDesc() method should return a short description of the expression interpreter, e.g., the name of the developer of the code.
6174 *
6175 * @subsection SCIPexprintGetCapability
6176 *
6177 * The SCIPexprintGetCapability() method should return a bitmask that indicates the capabilities of the expression interpreter,
6178 * i.e., whether it can compute gradients and Hessians.
6179 *
6180 * @subsection SCIPexprintCreate
6181 *
6182 * The SCIPexprintCreate() method is called to create an expression interpreter data structure.
6183 * The method should initialize a `struct SCIP_ExprInt` here.
6184 *
6185 * @subsection SCIPexprintFree
6186 *
6187 * The SCIPexprintFree() method is called to free an expression interpreter data structure.
6188 * The method should free a `struct SCIP_ExprInt` here.
6189 *
6190 * @subsection SCIPexprintCompile
6191 *
6192 * The SCIPexprintCompile() method is called to initialize the data structures that are required to evaluate a particular expression.
6193 * The expression interpreter can create and return data that is particular to a given expression in the argument `exprintdata`.
6194 *
6195 * @subsection SCIPexprintFreeData
6196 *
6197 * The SCIPexprintFreeData() method is called to free the data that is particular to a given expression and was possibly created in SCIPexprintCompile().
6198 *
6199 * @subsection SCIPexprintGetExprCapability
6200 *
6201 * The SCIPexprintGetExprCapability() method is called to request the capability to evaluate a specific expression by the expression interpreter.
6202 *
6203 * In cases of user-given expressions, higher order derivatives may not be available for the user-expression,
6204 * even if the expression interpreter could handle these. This method allows to recognize that, e.g., the
6205 * Hessian for an expression is not available because it contains a user expression that does not provide
6206 * Hessians.
6207 *
6208 * @subsection SCIPexprintEval
6209 *
6210 * The SCIPexprintEval() method is called when the value of an expression should be computed for a point.
6211 *
6212 * @subsection SCIPexprintGrad
6213 *
6214 * The SCIPexprintGrad() method is called when the gradient of an expression represented by an expression should be computed for a point.
6215 *
6216 * @subsection SCIPexprintHessianSparsity
6217 *
6218 * The SCIPexprintHessianSparsity() method is called when the sparsity structure of the Hessian matrix should be computed and returned.
6219 * Only the position of nonzero entries in the lower-triangular part of Hessian should be reported.
6220 *
6221 * @subsection SCIPexprintHessian
6222 *
6223 * The SCIPexprintHessian() method is called when the Hessian of an expression should be computed for a point.
6224 */
6225
6226/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6227
6228/**@page TABLE How to add statistics tables
6229 *
6230 * After solving a constraint integer program, SCIP can display statistics tables with information about, e.g., the solving time,
6231 * number of nodes, LP iterations or the number of calls and successes of different plugins via "display statistics" in the shell
6232 * or via SCIPprintStatistics() in the C-interface. There already exists a wide variety of statistics tables which can be activated
6233 * or deactivated on demand, see src/scip/table_default.c. Additionally, the user can implement his/her own statistics tables
6234 * in order to display problem or algorithm specific values.
6235 * \n
6236 * A complete list of all statistics tables contained in this release can be found \ref TABLES "here".
6237 *
6238 * We now explain how users can add their own statistics tables.
6239 * We give the explanation for creating your own source file for each additional statistics table. Of course, you can collect
6240 * different additional statistics tables in one source file.
6241 * Take src/scip/table_default.c, where all default statistics tables are collected, as an example.
6242 * As all other default plugins, the default statistics table plugins and the statistics table template are written in C.
6243 * C++ users can easily adapt the code by using the scip::ObjTable wrapper base class and implement the scip_...() virtual methods
6244 * instead of the SCIP_DECL_TABLE... callback methods.
6245 *
6246 *
6247 * Additional documentation for the callback methods of a statistics table can be found in the file type_table.h.
6248 *
6249 * Here is what you have to do to implement a statistics table (assuming your statistics table is named "mystatisticstable"):
6250 * -# Copy the template files src/scip/table_xyz.c and src/scip/table_xyz.h into files named "table_mystatisticstable.c"
6251 * and "table_mystatisticstable.h".
6252 * \n
6253 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
6254 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6255 * -# Use SCIPincludeTableMystatisticstable() in order to include the statistics table into your SCIP instance,
6256 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
6257 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
6258 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mystatisticstable".
6259 * -# Adjust the \ref TABLE_PROPERTIES "properties of the statistics table".
6260 * -# Define the \ref TABLE_DATA "statistics table data". This is optional.
6261 * -# Implement the \ref TABLE_INTERFACE "interface methods".
6262 * -# Implement the \ref TABLE_FUNDAMENTALCALLBACKS "fundamental callback methods".
6263 * -# Implement the \ref TABLE_ADDITIONALCALLBACKS "additional callback methods". This is optional.
6264 *
6265 *
6266 * @section TABLE_PROPERTIES Properties of a Statistics Table
6267 *
6268 * At the top of the new file "table_mystatisticstable.c" you can find the statistics table properties.
6269 * These are given as compiler defines.
6270 * In the C++ wrapper class, you have to provide the statistics table properties by calling the constructor
6271 * of the abstract base class scip::ObjTable from within your constructor.
6272 * The properties you have to set have the following meaning:
6273 *
6274 * \par TABLE_NAME: the name of the statistics table.
6275 * This name is used in the interactive shell to address the statistics table.
6276 * Additionally, if you are searching for a statistics table with SCIPfindTable(), this name is looked up.
6277 * Names have to be unique: no two statistic tables may have the same name.
6278 *
6279 * \par TABLE_DESC: the description of the statistics table.
6280 * This string is printed as a description of the statistics table in the interactive shell.
6281 *
6282 * \par TABLE_POSITION: the position of the statistics table.
6283 * In the statistics output, the statistics tables will be ordered by increasing position. Compare with the
6284 * default statistics tables in "table_default.c" to find a value which will give you the desired position
6285 * between the default statistics tables. If you give your table a negative position value, it will appear
6286 * before all SCIP statistcs, with a value larger than 20000 it will appear after all default statistics.
6287 *
6288 * \par TABLE_EARLIEST_STAGE: output of the statistics table is only printed from this stage onwards
6289 * The output routine of your statistics table will only be called if SCIP has reached this stage. For
6290 * example, the default table "tree" will only output information starting from SCIP_STAGE_SOLVING, because
6291 * there is no meaningful information available before, while the "presolver" table can already be called
6292 * in SCIP_STAGE_TRANSFORMED.
6293 *
6294 * @section TABLE_DATA Statistics Table Data
6295 *
6296 * Below the header "Data structures" you can find a struct which is called "struct SCIP_TableData".
6297 * In this data structure, you can store the data of your statistics table. For example, you should store the adjustable
6298 * parameters of the statistics table in this data structure.
6299 * If you are using C++, you can add statistics table data as usual as object variables to your class.
6300 * \n
6301 * Defining statistics table data is optional. You can leave the struct empty.
6302 *
6303 *
6304 * @section TABLE_INTERFACE Interface Methods
6305 *
6306 * At the bottom of "table_mystatisticstable.c" you can find the interface method SCIPincludeTableMystatisticstable(), which also
6307 * appears in "table_mystatisticstable.h".
6308 * \n
6309 * This method only has to be adjusted slightly.
6310 * It is responsible for notifying SCIP of the presence of the statistics table by calling the method
6311 * SCIPincludeTable().
6312 *
6313 * 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
6314 * application.
6315 *
6316 * If you are using statistics table data, you have to allocate the memory for the data at this point.
6317 * You can do this by calling:
6318 * \code
6319 * SCIP_CALL( SCIPallocBlockMemory(scip, &tabledata) );
6320 * \endcode
6321 * You also have to initialize the fields in struct SCIP_TableData afterwards.
6322 *
6323 * Although this is very uncommon, you may also add user parameters for your statistics table, see the method
6324 * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
6325 *
6326 *
6327 * @section TABLE_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Statistics Table
6328 *
6329 * Statistics table plugins have only one fundamental callback method, namely the \ref TABLEOUTPUT method.
6330 * This method has to be implemented for every display column; the other callback methods are optional.
6331 * In the C++ wrapper class scip::ObjTable, the scip_output() method (which corresponds to the \ref TABLEOUTPUT callback) is a virtual
6332 * abstract member function.
6333 * You have to implement it in order to be able to construct an object of your statistics table class.
6334 *
6335 * Additional documentation for the callback methods can be found in type_table.h.
6336 *
6337 * @subsection TABLEOUTPUT
6338 *
6339 * The TABLEOUTPUT callback is called whenever SCIP is asked to print statistics (because the user typed "display statistics"
6340 * in the shell or called SCIPprintStatistics()). In this callback, the table should print all of its information to the given file
6341 * (which may be NULL if the output should be printed to the console).
6342 *
6343 * Typical methods called by a statistics table are, for example, SCIPdispLongint(), SCIPdispInt(), SCIPdispTime(), and
6344 * SCIPinfoMessage().
6345 *
6346 *
6347 * @section TABLE_ADDITIONALCALLBACKS Additional Callback Methods of a Statistics Table
6348 *
6349 * The additional callback methods do not need to be implemented in every case.
6350 * They can be used, for example, to initialize and free private data.
6351 *
6352 * @subsection TABLECOPY
6353 *
6354 * The TABLECOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this callback
6355 * as <code>NULL</code> the user disables the execution of the specified column. In general it is probably not needed to
6356 * implement that callback since the output of the copied instance is usually suppressed. In the other case or for
6357 * debugging the callback should be implement.
6358 *
6359 *
6360 * @subsection TABLEFREE
6361 *
6362 * If you are using statistics table data, you have to implement this method in order to free the statistics table data.
6363 * This can be done by the following procedure:
6364 * @refsnippet{tests/src/misc/snippets.c,SnippetTableFree}
6365 *
6366 * If you have allocated memory for fields in your statistics table data, remember to free this memory
6367 * before freeing the statistics table data itself.
6368 * If you are using the C++ wrapper class, this method is not available.
6369 * Instead, just use the destructor of your class to free the member variables of your class.
6370 *
6371 * @subsection TABLEINIT
6372 *
6373 * The TABLEINIT callback is executed after the problem is transformed.
6374 * The statistics table may, e.g., use this call to initialize its statistics table data.
6375 *
6376 * @subsection TABLEEXIT
6377 *
6378 * The TABLEEXIT callback is executed before the transformed problem is freed.
6379 * In this method, the statistics table should free all resources that have been allocated for the solving process in
6380 * \ref TABLEINIT.
6381 *
6382 * @subsection TABLEINITSOL
6383 *
6384 * The TABLEINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
6385 * begin. The statistics table may use this call to initialize its branch-and-bound specific data.
6386 *
6387 * @subsection TABLEEXITSOL
6388 *
6389 * The TABLEEXITSOL callback is executed before the branch-and-bound process is freed. The statistics table should use this
6390 * call to clean up its branch-and-bound specific data.
6391 */
6392
6393/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6394
6395/**@page BENDER How to add custom Benders' decomposition implementations
6396 *
6397 * Benders' decomposition is a very popular mathematical programming technique that is applied to solve structured
6398 * problems. Problems that display a block diagonal structure are particularly amenable to the application of Benders'
6399 * decomposition. Such problems are given by
6400 *
6401 * \f[
6402 * \begin{array}[t]{rllclcl}
6403 * \min & \displaystyle & c^{T}x & + & d^{T}y \\
6404 * & \\
6405 * subject \ to & \displaystyle & Ax & & & = & b \\
6406 * & \\
6407 * & \displaystyle & Tx & + & Hy & = & h \\
6408 * & \\
6409 * & & x & & & \in & \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
6410 * & & & & y & \in & \mathbb{R}^{m} \\
6411 * \end{array}
6412 * \f]
6413 *
6414 * The variables \f$x\f$ and \f$y\f$ are described as the first and second stage variables respectively. In the
6415 * classical use of Benders' decomposition, it is a requirement that the all second stage variables are continuous.
6416 * Extensions to the classical Benders' decomposition approach have permitted the use of more general second stage
6417 * problems.
6418 *
6419 * The application of Benders' decomposition to the above problem results in a subproblem, given by
6420 *
6421 * \f[
6422 * \begin{array}[t]{rll}
6423 * \min & \displaystyle & d^{T}y \\
6424 * & \\
6425 * subject \ to & \displaystyle & Hy = h - T\bar{x} \\
6426 * & \\
6427 * & & y \in \mathbb{R}^{m} \\
6428 * \end{array}
6429 * \f]
6430 *
6431 * where \f$\bar{x}\f$ is a solution vector of the first stage variables. As such, the subproblem is a problem only in
6432 * \f$y\f$. The dual solution to the subproblem, either an extreme point or extreme ray, is used to generate cuts that
6433 * are added to the master problem. Let \f$\lambda\f$ be the vector of dual variables associated with the set of
6434 * constraints from the subproblem. If, for a given \f$\bar{x}\f$, the subproblem is infeasible, then \f$\lambda\f$
6435 * corresponds to a dual ray and is used to produce the cut
6436 *
6437 * \f[
6438 * 0 \geq \lambda(h - Tx)
6439 * \f]
6440 *
6441 * which eliminates \f$\bar{x}\f$ from the master problem. If, for a given \f$\bar{x}\f$, the subproblem is feasible,
6442 * then \f$\lambda\f$ corresponds to a dual extreme point and is used to produce the cut
6443 *
6444 * \f[
6445 * \varphi \geq \lambda(h - Tx)
6446 * \f]
6447 *
6448 * where \f$\varphi\f$ is an auxiliary variable added to the master problem as an underestimator of the optimal
6449 * subproblem objective function value.
6450 *
6451 * Given \f$\Omega^{p}\f$ and \f$\Omega^{r}\f$ as the sets of dual extreme points and rays of the subproblem,
6452 * respectively, the Benders' decomposition master problem is given by
6453 *
6454 * \f[
6455 * \begin{array}[t]{rll}
6456 * \min & \displaystyle & c^{T}x + \varphi \\
6457 * & \\
6458 * subject \ to & \displaystyle & Ax = b \\
6459 * & \\
6460 * & \displaystyle & \varphi \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r}\\
6461 * & \\
6462 * & \displaystyle & 0 \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r} \\
6463 * & \\
6464 * & & x \in \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
6465 * & & \varphi \in \mathbb{R} \\
6466 * \end{array}
6467 * \f]
6468 *
6469 * The Benders' decomposition framework of SCIP allows the user to provide a custom implementation of many aspects of
6470 * the Benders' decomposition algorithm. It is possible to implement multiple Benders' decompositions that work in
6471 * conjunction with each other. Such a situation is where you may have different formulations of the Benders'
6472 * decomposition subproblem.
6473 *
6474 * The current list of all Benders' decomposition implementations available in this release can be found \ref BENDERS
6475 * "here".
6476 *
6477 * We now explain how users can add their own Benders' decomposition implementations.
6478 * Take the default Benders' decomposition implementation (src/scip/benders_default.c) as an example. Same as all other
6479 * default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjBenders wrapper base
6480 * class and implement the scip_...() virtual methods instead of the SCIP_DECL_BENDERS... callback methods.
6481 *
6482 * Additional documentation for the callback methods of a Benders' decomposition implementation, in particular for the
6483 * input parameters, can be found in the file type_benders.h.
6484 *
6485 * Here is what you have to do to implement a custom Benders' decomposition:
6486 * -# Copy the template files src/scip/benders_xyz.c and src/scip/benders_xyz.h into files "benders_mybenders.c" and
6487 * "benders_mybenders.h".
6488 \n
6489 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
6490 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6491 * -# Use SCIPincludeBendersMybenders() in order to include the Benders' decomposition into your SCIP instance, e.g., in
6492 * the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
6493 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
6494 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mybenders".
6495 * -# Adjust the properties of the Benders' decomposition (see \ref BENDERS_PROPERTIES).
6496 * -# Define the Benders' decomposition data (see \ref BENDERS_DATA). This is optional.
6497 * -# Implement the interface methods (see \ref BENDERS_INTERFACE).
6498 * -# Implement the fundamental callback methods (see \ref BENDERS_FUNDAMENTALCALLBACKS).
6499 * -# Implement the additional callback methods (see \ref BENDERS_ADDITIONALCALLBACKS). This is optional.
6500 *
6501 *
6502 * @section BENDERS_PROPERTIES Properties of a Benders' decomposition
6503 *
6504 * At the top of the new file "benders_mybenders.c", you can find the Benders' decomposition properties.
6505 * These are given as compiler defines.
6506 * In the C++ wrapper class, you have to provide the Benders' decomposition properties by calling the constructor
6507 * of the abstract base class scip::ObjBenders from within your constructor.
6508 * The properties you have to set have the following meaning:
6509 *
6510 * \par BENDERS_NAME: the name of the Benders' decomposition.
6511 * This name is used in the interactive shell to address the Benders' decomposition.
6512 * Additionally, if you are searching for a Benders' decomposition with SCIPfindBenders(), this name is looked up.
6513 * Names have to be unique: no two Benders' decompositions may have the same name.
6514 *
6515 * \par BENDERS_DESC: the description of the Benders' decomposition.
6516 * This string is printed as a description of the Benders' decomposition in the interactive shell.
6517 *
6518 * \par BENDERS_PRIORITY: the priority of the Benders' decomposition.
6519 * During the enforcement and checking of solutions in src/scip/cons_benders.c and src/scip/cons_benderslp.c, every
6520 * active Benders' decompositions are called. The execution method of the Benders' decomposition calls each of the
6521 * subproblems and generates cuts from their solutions. So the active Benders' decompositions are called in order of
6522 * priority until a cut is generated or feasibility is proven.
6523 * \n
6524 * The priority of the Benders' decomposition should be set according to the difficulty of solving the subproblems and
6525 * the generation of cuts. However, it is possible to prioritise the Benders' decompositions with respect to the
6526 * strength of the subproblem formulation and the resulting cuts.
6527 *
6528 * \par BENDERS_CUTLP: should Benders' decomposition cuts be generated during the enforcement of LP solutions.
6529 * This is a flag that is used by src/scip/cons_benders.c and src/scip/cons_benderslp.c to idicate whether the
6530 * enforcement of LP solutions should involve solving the Benders' decomposition subproblems. This should be set to TRUE
6531 * to have an exact solution algorithm. In the presence of multiple Benders' decomposition, it may be desired to enforce
6532 * the LP solutions for only a subset of those implemented.
6533 *
6534 * \par BENDERS_CUTRELAX: should Benders' decomposition cuts be generated during the enforcement of relaxation solutions.
6535 * This is a flag that is used by src/scip/cons_benders.c and src/scip/cons_benderslp.c to idicate whether the
6536 * enforcement of relaxation solutions should involve solving the Benders' decomposition subproblems. This should be
6537 * set to TRUE to have an exact solution algorithm. In the presence of multiple Benders' decomposition, it may be desired
6538 * to enforce the relaxation solutions for only a subset of those implemented. This parameter will only take effect if
6539 * external relaxation have been implemented.
6540 *
6541 * \par BENDERS_CUTPSEUDO: should Benders' decomposition subproblems be solved during the enforcement of pseudo solutions.
6542 * This is a flag that is used by src/scip/cons_benders.c and src/scip/cons_benderslp.c to indicate whether the
6543 * enforcement of pseudo solutions should involve solving the Benders' decomposition subproblems. This should be set to
6544 * TRUE, since not enforcing pseudo solutions could result in an error or suboptimal result. During the enforcement of
6545 * pseudo solutions, no cuts are generated. Only a flag to indicate whether the solution is feasible or if the LP should
6546 * be solved again is returned.
6547 *
6548 * \par BENDERS_SHAREAUXVARS: should this Benders' decomposition use the auxiliary variables from the highest priority
6549 * Benders' decomposition.
6550 * This parameter only takes effect if multiple Benders' decompositions are implemented. Consider the case that two Benders'
6551 * decompositions are implemented with different formulations of the subproblem. Since the subproblems in each of the
6552 * decomposition will have the same optimal solution, then it is useful to only have a single auxiliary variable for the
6553 * two different subproblems. This means that when an optimality cut is generated in the lower priority Benders'
6554 * decomposition, the auxiliary variable from the highest priority Benders' decomposition will be added to the right
6555 * hand side.
6556 *
6557 * @section BENDERS_DATA Benders' decomposition Data
6558 *
6559 * Below the header "Data structures" you can find a struct which is called "struct SCIP_BendersData".
6560 * In this data structure, you can store the data of your Benders' decomposition. For example, you should store the adjustable
6561 * parameters of the Benders' decomposition in this data structure. In a Benders' decomposition, user parameters for the
6562 * number of subproblems and an array to store the subproblem SCIP instances could be useful.
6563 * \n
6564 * Defining Benders' decomposition data is optional. You can leave the struct empty.
6565 *
6566 * @section BENDERS_INTERFACE Interface Methods
6567 *
6568 * At the bottom of "benders_mybenders.c", you can find the interface method SCIPincludeBendersMybenders(),
6569 * which also appears in "benders_mybenders.h"
6570 * SCIPincludeBendersMybenders() is called by the user, if (s)he wants to include the Benders' decomposition,
6571 * i.e., if (s)he wants to use the Benders' decomposition in his/her application.
6572 *
6573 * This method only has to be adjusted slightly.
6574 * It is responsible for notifying SCIP of the presence of the Benders' decomposition. For this, you can either call SCIPincludeBenders(),
6575 * or SCIPincludeBendersBasic() since SCIP version 3.0. In the latter variant, \ref BENDERS_ADDITIONALCALLBACKS "additional callbacks"
6576 * must be added via setter functions as, e.g., SCIPsetBendersCopy(). We recommend this latter variant because
6577 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
6578 * variant must be manually adjusted with every SCIP release containing new callbacks for Benders' decompositions in order to compile.
6579 *
6580 * If you are using Benders' decomposition data, you have to allocate the memory
6581 * for the data at this point. You can do this by calling:
6582 * \code
6583 * SCIP_CALL( SCIPallocBlockMemory(scip, &bendersdata) );
6584 * \endcode
6585 * You also have to initialize the fields in "struct SCIP_BendersData" afterwards. For freeing the
6586 * Benders' decomposition data, see \ref BENDERSFREE.
6587 *
6588 * You may also add user parameters for your Benders' decomposition, see \ref PARAM for how to add user parameters and
6589 * the method SCIPincludeBendersDefault() in src/scip/benders_default.c for an example.
6590 *
6591 * It is advised to disable presolving for the Benders' decomposition master problem by calling SCIPsetPresolving() with
6592 * the parameter SCIP_PARAMSETTING_OFF. Presolving should be disabled because reductions on the master problem could be
6593 * invalid since constraints have been transferred to the subproblems. It is not necessary to disable all presolving,
6594 * but care must be taken when it is used for the Benders' decomposition master problem.
6595 *
6596 * The Benders' decomposition constraint handler, see src/scip/cons_benders.c, includes a presolver for tightening the
6597 * bound on the auxiliary variables. This presolver can be enabled with by setting "presolving/maxround" to 1 and
6598 * "constraints/benders/maxprerounds" to 1. This presolver solves the Benders' decomposition subproblems without fixing
6599 * the master problem variables to find a lower bound for the auxiliary variable.
6600 *
6601 *
6602 * @section BENDERS_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Benders' decomposition
6603 *
6604 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
6605 * an operational algorithm.
6606 * They are passed together with the Benders' decomposition itself to SCIP using SCIPincludeBenders() or SCIPincludeBendersBasic(),
6607 * see @ref BENDERS_INTERFACE.
6608 *
6609 * Benders' decomposition plugins have two callbacks, @ref BENDERSGETVAR and @ref BENDERSCREATESUB that must be implemented.
6610 *
6611 * Additional documentation for the callback methods, in particular to their input parameters,
6612 * can be found in type_benders.h.
6613 *
6614 * @subsection BENDERSGETVAR
6615 *
6616 * The BENDERSGETVAR callback provides a mapping between the master problem variables and their corresponding subproblem
6617 * variables, and vice versa. The parameters of this function include the variable for which the mapped variable is
6618 * desired and the problem number for the mapped variable. When requesting a subproblem variable for a given master
6619 * problem variable, the master variable is input with the appropriate subproblem index. If a master problem variable is
6620 * requested for a given subproblem variable, then the subproblem variable is input with the subproblem index given as
6621 * -1.
6622 *
6623 * An example of how to implement the mapping between the master and subproblem variables is shown by
6624 *
6625 * @refsnippet{src/scip/benders_default.c,SnippetBendersGetvarDefault}
6626 *
6627 * In the above code snippet, the hashmaps providing the mapping between the master and subproblem variables are
6628 * constructed in the <code>SCIP_STAGE_INIT</code> stage (see \ref BENDERSINIT).
6629 *
6630 * The requested variable is returned via the mappedvar parameter. There may not exist a corresponding master
6631 * (subproblem) variable for every input subproblem (master) variable. In such cases were no corresponding variable
6632 * exists, mappedvar must be returned as NULL.
6633 *
6634 * The mapped variables are retrieved by calling SCIPgetBendersMasterVar() and SCIPgetBendersSubproblemVar().
6635 *
6636 * The variable mapping must be created before <code>SCIP_STAGE_PRESOLVE</code> stage. This is because the variable
6637 * mapping is required for checking solutions found by heuristics during presolving.
6638 *
6639 * @subsection BENDERSCREATESUB
6640 *
6641 * The BENDERSCREATESUB callback is executed during the <code>SCIP_STAGE_INIT</code> stage. In this function, the
6642 * user must register the SCIP instances for each subproblem. The BENDERSCREATESUB callback is executed once for each
6643 * subproblem. The user registers a subproblem by calling SCIPbendersAddSubproblem().
6644 *
6645 * It is possible to build the SCIP instance for the subproblem during the execution of this callback. However, it may
6646 * be more convenient to build the subproblem instances during the problem creation stage of the master problem and
6647 * store the subproblem SCIP instances in SCIP_BendersData. This approach is used in src/scip/benders_default.c.
6648 *
6649 * @section BENDERS_ADDITIONALCALLBACKS Additional Callback Methods of a Benders' decomposition implementation
6650 *
6651 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
6652 * implemented for most applications, they can be used, for example, to initialize and free private data.
6653 * Additional callbacks can either be passed directly with SCIPincludeBenders() to SCIP or via specific
6654 * <b>setter functions</b> after a call of SCIPincludeBendersBasic(), see also @ref BENDERS_INTERFACE.
6655 *
6656 * @subsection BENDERSFREE
6657 *
6658 * If you are using Benders' decomposition data (see \ref BENDERS_DATA and \ref BENDERS_INTERFACE), you have to
6659 * implement this method in order to free the Benders' decomposition data. This can be done by the following procedure:
6660 *
6661 * @refsnippet{src/scip/benders_default.c,SnippetBendersFreeDefault}
6662 *
6663 * If you have allocated memory for fields in your Benders' decomposition data, remember to free this memory
6664 * before freeing the Benders' decomposition data itself.
6665 * If you are using the C++ wrapper class, this method is not available.
6666 * Instead, just use the destructor of your class to free the member variables of your class.
6667 *
6668 * @subsection BENDERSCOPY
6669 *
6670 * The BENDERSCOPY callback is executed when a SCIP instance is copied, e.g. to
6671 * solve a sub-SCIP. By
6672 * defining this callback as
6673 * <code>NULL</code> the user disables the execution of the specified
6674 * separator for all copied SCIP instances. This may deteriorate the performance
6675 * of primal heuristics using sub-SCIPs.
6676 *
6677 * If a user wishes to employ the Large Neighbourhood Benders' Search, it is necessary for the BENDERSCOPY callback to
6678 * be implemented. This is required because the sub-SCIP instances of large neighbourhood search heuristics can only
6679 * access the implemented Benders' decomposition if it is copied via the BENDERSCOPY callback.
6680 *
6681 * @subsection BENDERSINIT
6682 *
6683 * The BENDERSINIT callback is executed after the problem is transformed.
6684 * The Benders' decomposition implementation may, e.g., use this call to initialize its Benders' decomposition data. In
6685 * src/scip/benders_default.c BENDERSINIT is used to create the mapping between the master and subproblem variables.
6686 * The difference between the original and the transformed problem is explained in
6687 * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
6688 *
6689 * @subsection BENDERSEXIT
6690 *
6691 * The BENDERSEXIT callback is executed before the transformed problem is freed.
6692 * In this method, the Benders' decomposition implementation should free all resources that have been allocated for
6693 * the solving process in BENDERSINIT.
6694 *
6695 * @subsection BENDERSINITPRE
6696 *
6697 * The BENDERSINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
6698 * The Benders' decomposition may use this call to initialize its presolving data before the presolving process begins.
6699 *
6700 * @subsection BENDERSEXITPRE
6701 *
6702 * The BENDERSEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
6703 * The Benders' decomposition implementation may use this call, e.g., to clean up its presolving data.
6704 * Besides clean up, no time consuming operations should be done.
6705 *
6706 * @subsection BENDERSINITSOL
6707 *
6708 * The BENDERSINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
6709 * begin. The Benders' decomposition implementation may use this call to initialize its branch-and-bound specific data.
6710 *
6711 * @subsection BENDERSEXITSOL
6712 *
6713 * The BENDERSEXITSOL callback is executed before the branch-and-bound process is freed. The Benders' decomposition
6714 * implementation should use this call to clean up its branch-and-bound data.
6715 *
6716 * @subsection BENDERSPRESUBSOLVE
6717 *
6718 * The BENDERSPRESUBSOLVE callback is provided to give the user an opportunity in each iteration to perform any setup
6719 * operations prior to solving the subproblems. This callback also allows the user to skip the subproblem solve for the
6720 * current iteration. In this case, the user must set the result parameter appropriately
6721 * - the subproblem was not solved in this iteration. Other decompositions will be checked (SCIP_DIDNOTRUN).
6722 * - a constraint has been added to the master problem. No other decompositions will be checked (SCIP_CONSADDED).
6723 * - a cut has been added to the master problem. No other decompositions will be checked (SCIP_SEPARATED).
6724 * - feasibility of the solution is reported to SCIP. Other decompositions will be checked (SCIP_FEASIBLE).
6725 * - infeasibility of the solution is reported to SCIP. No other decompositions will be checked (SCIP_INFEASIBLE).
6726 *
6727 * @subsection BENDERSSOLVESUBCONVEX
6728 *
6729 * Two different subproblem solving functions are provide in the Benders' decomposition framework, BENDERSSOLVESUBCONVEX
6730 * and BENDERSSOLVESUB. These two solving functions are used in the two solving loops of the Benders' decomposition
6731 * framework. The first solving loop solves convex subproblems and convex relaxations of CIPs. The BENDERSSOLVESUBCONVEX
6732 * callback is executed only during the FIRST solving loop. Benders' cut generating methods suitable for convex
6733 * subproblems are executed during this solving loop. If a cut is found, then the second solve loop is not executed. If
6734 * your decomposition does not have any convex subproblems, then it is not necessary to implement the
6735 * BENDERSSOLVESUBCONVEX callback. However, it may be computationally beneficial to solve the convex relaxation of CIP
6736 * subproblems, such as the LP relaxation of a MIP subproblem.
6737 *
6738 * The second solve loop expects that the CIP subproblems are solved to optimality.
6739 *
6740 * If you implement the BENDERSSOLVESUBCONVEX callback, it is necessary to implement the BENDERSFREESUB callback.
6741 *
6742 * The objective function value after the subproblem solve and the result must be returned. The permissible results
6743 * are:
6744 * - the subproblem was not solved in this iteration (SCIP_DIDNOTRUN)
6745 * - the subproblem is solved and is feasible (SCIP_FEASIBLE)
6746 * - the subproblem is solved and is infeasible (SCIP_INFEASIBLE)
6747 * - the subproblem is solved and is unbounded (SCIP_UNBOUNDED)
6748 *
6749 * @subsection BENDERSSOLVESUB
6750 *
6751 * The BENDERSSOLVESUB is executed only during the SECOND solve loop. This callback function is used to solve CIP
6752 * subproblems. If your decomposition does not have any CIP subproblems, then it is not necessary to implement the
6753 * BENDERSSOLVESUB callback.
6754 *
6755 * If you implement the BENDERSSOLVESUB callback, it is necessary to implement the BENDERSFREESUB callback.
6756 *
6757 * The objective function value after the subproblem solve and the result must be returned. The permissible results
6758 * are:
6759 * - the subproblem was not solved in this iteration (SCIP_DIDNOTRUN)
6760 * - the subproblem is solved and is feasible (SCIP_FEASIBLE)
6761 * - the subproblem is solved and is infeasible (SCIP_INFEASIBLE)
6762 * - the subproblem is solved and is unbounded (SCIP_UNBOUNDED)
6763 *
6764 * @subsection BENDERSPOSTSOLVE
6765 *
6766 * The BENDERSPOSTSOLVE callback is executed after the subproblems have been solved and any required cuts have been
6767 * generated, but before the subproblems are freed. This callback provides the user an opportunity to interact the
6768 * subproblems at a global level. For example, the user is able to construct a solution to the original problem by
6769 * combining the solutions from the master problem and all subproblems.
6770 *
6771 * Additionally, the user is able to merge subproblems into the master problem during the execution of this callback.
6772 * The merging of subproblems into the master problem could be desired if it is too time consuming to satisfy the
6773 * feasibility of a subproblem or the appropriate cutting methods are not available for the provided subproblem. A list
6774 * of indicies of subproblems suitable for merging are given in the mergecands array. The first npriomergecands are the
6775 * merge candidates that must be merged into the master problem. If they are not, then the solution process will
6776 * terminate with an error. These merge candidates arise if a cut could not be generated due to numerical difficulties.
6777 * The remaining nmergecands - npriomergecands are subproblems that could be merged into the master problem if desired
6778 * by the user.
6779 *
6780 * @subsection BENDERSFREESUB
6781 *
6782 * The BENDERSFREESUB callback is executed to clean up the subproblems after the solving process and prepare them for
6783 * the next iteration. Typically, SCIPfreeTransform() is called for each subproblem to free the transformed problem.
6784 *
6785 */
6786
6787/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6788
6789/**@page BENDERSCUT How to add custom Benders' decomposition cut generation methods
6790 *
6791 * The Benders' decomposition framework of SCIP allows the user to provide a custom implementation of cut generation
6792 * methods. The Benders' decomposition cut methods are linked to the Benders' decomposition implementations, not the
6793 * master problem SCIP instance. As such, you are able to have different Benders' decomposition cut methods for each
6794 * included Benders' decomposition.
6795 * The current list of all Benders' decomposition cut generation methods available in this release can be found
6796 * \ref BENDERSCUTS "here".
6797 *
6798 * We now explain how users can add their own Benders' decomposition cut methods. Take the default Benders'
6799 * decomposition cut method (src/scip/benderscut_opt.c) as an example. This Benders' decomposition cut method generates
6800 * a classical optimality cut from the optimal dual solution to the convex relaxation of the Benders' decomposition
6801 * subproblem. Same as all other default plugins, it is written in C. C++ users can easily adapt the code by using the
6802 * scip::ObjBenderscut wrapper base class and implement the scip_...() virtual methods instead of the
6803 * SCIP_DECL_BENDERSCUT... callback methods.
6804 *
6805 * Additional documentation for the callback methods of a Benders' decomposition cut methods, in particular for the
6806 * input parameters, can be found in the file type_benderscut.h.
6807 *
6808 * Here is what you have to do to implement a custom Benders' decomposition cut method:
6809 * -# Copy the template files src/scip/benderscut_xyz.c and src/scip/benderscut_xyz.h into files "benderscut_mybenderscut.c" and
6810 * "benderscut_mybenderscut.h".
6811 \n
6812 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
6813 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6814 * -# Use SCIPincludeBenderscutMybenderscut() in order to include the Benders' decomposition cut method into your SCIP
6815 * instance, e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
6816 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
6817 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mybenderscut".
6818 * -# Adjust the properties of the Benders' decomposition (see \ref BENDERSCUT_PROPERTIES).
6819 * -# Define the Benders' decomposition data (see \ref BENDERSCUT_DATA). This is optional.
6820 * -# Implement the interface methods (see \ref BENDERSCUT_INTERFACE).
6821 * -# Implement the fundamental callback methods (see \ref BENDERSCUT_FUNDAMENTALCALLBACKS).
6822 * -# Implement the additional callback methods (see \ref BENDERSCUT_ADDITIONALCALLBACKS). This is optional.
6823 *
6824 *
6825 * @section BENDERSCUT_PROPERTIES Properties of a Benders' decomposition
6826 *
6827 * At the top of the new file "benderscut_mybenderscut.c", you can find the Benders' decomposition cut methods
6828 * properties. These are given as compiler defines.
6829 * In the C++ wrapper class, you have to provide the Benders' decomposition properties by calling the constructor
6830 * of the abstract base class scip::ObjBenderscut from within your constructor.
6831 * The properties you have to set have the following meaning:
6832 *
6833 * \par BENDERSCUT_NAME: the name of the Benders' decomposition cut method.
6834 * This name is used in the interactive shell to address the Benders' decomposition cut method.
6835 * Additionally, if you are searching for a Benders' decomposition cut method with SCIPfindBenderscut(), this name is
6836 * looked up. Names have to be unique: no two Benders' decomposition cut methods linked to the same Benders'
6837 * decomposition may have the same name.
6838 *
6839 * \par BENDERSCUT_DESC: the description of the Benders' decomposition cut method.
6840 * This string is printed as a description of the Benders' decomposition cut method in the interactive shell.
6841 *
6842 * \par BENDERSCUT_PRIORITY: the priority of the Benders' decomposition cut method.
6843 * In each of the Benders' decomposition subproblem solving loops, the included Benders' decomposition cut methods are
6844 * called in order of priority. The priority is important because once a cut is generated for a subproblem, no other
6845 * cuts are generated for that subproblem for that solving loop.
6846 * \n
6847 * The priority of the Benders' decomposition should be set according to the order in which the cut should be generated.
6848 * For example, the priority of the included cuts attempt to generation feasibility cuts (src/scip/benderscut_feas.c
6849 * and src/scip/benderscut_nogood.c) prior to attempting to generate optimality cuts.
6850 *
6851 * \par BENDERSCUT_LPCUT: Can this cut be applied to convex subproblems and convex relaxations of CIP subproblems?
6852 * Since the Benders' decomposition framework executes two different solving loops, one for convex subproblems and the
6853 * other for CIP subproblems, the Benders' decomposition cut methods must be partitioned by their suitability for each
6854 * subproblem type. If BENDERSCUT_LPCUT is set to TRUE, then this cut is only applied to convex subproblems and convex
6855 * relaxations of CIP subproblems.
6856 *
6857 * @section BENDERSCUT_DATA Benders' decomposition Data
6858 *
6859 * Below the header "Data structures" you can find a struct which is called "struct SCIP_BenderscutData".
6860 * In this data structure, you can store the data of your Benders' decomposition. For example, you should store the adjustable
6861 * parameters of the Benders' decomposition in this data structure. In a Benders' decomposition, user parameters for the
6862 * number of subproblems and an array to store the subproblem SCIP instances could be useful.
6863 * \n
6864 * Defining Benders' decomposition data is optional. You can leave the struct empty.
6865 *
6866 * @section BENDERSCUT_INTERFACE Interface Methods
6867 *
6868 * At the bottom of "benderscut_mybenderscut.c", you can find the interface method SCIPincludeBenderscutMybenderscut(),
6869 * which also appears in "benderscut_mybenderscut.h"
6870 * SCIPincludeBenderscutMybenderscut() is called by the user, if (s)he wants to include the Benders' decomposition,
6871 * i.e., if (s)he wants to use the Benders' decomposition in his/her application.
6872 *
6873 * This method only has to be adjusted slightly.
6874 * It is responsible for notifying SCIP of the presence of the Benders' decomposition. For this, you can either call SCIPincludeBenderscut(),
6875 * or SCIPincludeBenderscutBasic() since SCIP version 3.0. In the latter variant, \ref BENDERSCUT_ADDITIONALCALLBACKS "additional callbacks"
6876 * must be added via setter functions as, e.g., SCIPsetBenderscutCopy(). We recommend this latter variant because
6877 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
6878 * variant must be manually adjusted with every SCIP release containing new callbacks for Benders' decompositions in order to compile.
6879 *
6880 * If you are using Benders' decomposition cut data, you have to allocate the memory
6881 * for the data at this point. You can do this by calling:
6882 * \code
6883 * SCIP_CALL( SCIPallocBlockMemory(scip, &benderscutdata) );
6884 * \endcode
6885 * You also have to initialize the fields in "struct SCIP_BenderscutData" afterwards. For freeing the
6886 * Benders' decomposition cut data, see \ref BENDERSCUTFREE.
6887 *
6888 * You may also add user parameters for your Benders' decomposition, see \ref PARAM for how to add user parameters and
6889 * the method SCIPincludeBenderscutOpt() in src/scip/benderscut_opt.c for an example.
6890 *
6891 *
6892 * @section BENDERSCUT_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Benders' decomposition cut method
6893 *
6894 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
6895 * an operational algorithm.
6896 * They are passed together with the Benders' decomposition itself to SCIP using SCIPincludeBenderscut() or SCIPincludeBenderscutBasic(),
6897 * see @ref BENDERSCUT_INTERFACE.
6898 *
6899 * Benders' decomposition cut methods only one callback, @ref BENDERSCUTEXEC, that must be implemented.
6900 *
6901 * Additional documentation for the callback methods, in particular to their input parameters,
6902 * can be found in type_benderscut.h.
6903 *
6904 * @subsection BENDERSCUTEXEC
6905 *
6906 * The BENDERSCUTEXEC callback is called during the cut generation process within the Benders' decomposition subproblem
6907 * solving loop. This method must generate a cut for the given subproblem if the associated subsystem is not optimal
6908 * with respect to the checked master problem solution.
6909 *
6910 * When generating cuts, it is possible to store these within the SCIP_BendersData of the associated Benders'
6911 * decomposition. This is achieved by calling SCIPstoreBenderscutCons() (SCIPstoreBenderscutCut() if the Benders'
6912 * decomposition cut is added as a cutting plane instead as a constraint). The storing of cuts can be useful when using
6913 * the large neighbourhood Benders' search, where the cut generated in the sub-SCIP solve are transferred to the main
6914 * SCIP instance.
6915 *
6916 * The BENDERSCUTEXEC callback must return the result of the cut generation. The permissable results are:
6917 * - if the Benders' cut was not run (SCIP_DIDNOTRUN).
6918 * - if the Benders' cut was run, but there was an error in generating the cut (SCIP_DIDNOTFIND).
6919 * - if the Benders' decomposition cut algorithm has not generated a constraint or cut (SCIP_FEASIBLE).
6920 * - an additional constraint for the Benders' decomposition cut was generated (SCIP_CONSADDED).
6921 * - a cutting plane representing the Benders' decomposition cut was generated (SCIP_SEPARATED).
6922 *
6923 * If the BENDERSCUTEXEC callback returns SCIP_DIDNOTFIND due to an error in the cut generation, if no other subproblems
6924 * generate a cut during the same iteration of the Benders' decomposition algorithm, then this could result in an
6925 * error. It is possible to avoid the error by merging the subproblem into the master problem (see \ref
6926 * BENDERSPOSTSOLVE).
6927 *
6928 * @section BENDERSCUT_ADDITIONALCALLBACKS Additional Callback Methods of a Separator
6929 *
6930 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
6931 * implemented for most applications, they can be used, for example, to initialize and free private data.
6932 * Additional callbacks can either be passed directly with SCIPincludeBenderscut() to SCIP or via specific
6933 * <b>setter functions</b> after a call of SCIPincludeBenderscutBasic(), see also @ref BENDERSCUT_INTERFACE.
6934 *
6935 * @subsection BENDERSCUTFREE
6936 *
6937 * If you are using Benders' decomposition cut data (see \ref BENDERSCUT_DATA and \ref BENDERSCUT_INTERFACE), you have
6938 * to implement this method in order to free the Benders' decomposition cut data.
6939 *
6940 * If you have allocated memory for fields in your Benders' decomposition cut data, remember to free this memory
6941 * before freeing the Benders' decomposition data itself.
6942 * If you are using the C++ wrapper class, this method is not available.
6943 * Instead, just use the destructor of your class to free the member variables of your class.
6944 *
6945 * @subsection BENDERSCUTCOPY
6946 *
6947 * The BENDERSCUTCOPY callback is executed when a SCIP instance is copied, e.g. to
6948 * solve a sub-SCIP. By
6949 * defining this callback as
6950 * <code>NULL</code> the user disables the execution of the specified
6951 * separator for all copied SCIP instances. This may deteriorate the performance
6952 * of primal heuristics using sub-SCIPs.
6953 *
6954 * If the Benders' decomposition cuts are included by calling SCIPincludeBendersDefaultCuts() in the include method of
6955 * the Benders' decomposition implementation, such as SCIPincludeBendersDefault(), then it is not necessary to implement
6956 * BENDERSCUTCOPY. The copy method could be implemented to copy Benders' decomposition cut data from the original SCIP
6957 * instance to the sub-SCIP.
6958 *
6959 *
6960 * @subsection BENDERSCUTINIT
6961 *
6962 * The BENDERSCUTINIT callback is executed after the problem is transformed The Benders' decomposition cut method may,
6963 * e.g., use this call to initialize its Benders' decomposition cut data. The difference between the original and the
6964 * transformed problem is explained in "What is this thing with the original and the transformed problem about?" on \ref
6965 * FAQ.
6966 *
6967 * @subsection BENDERSCUTEXIT
6968 *
6969 * The BENDERSCUTEXIT callback is executed before the transformed problem is freed. In this method, the Benders'
6970 * decomposition cut method should free all resources that have been allocated for the solving process in
6971 * BENDERSCUTINIT.
6972 *
6973 * @subsection BENDERSCUTINITSOL
6974 *
6975 * The BENDERSCUTINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
6976 * begin. The Benders' decomposition implementation may use this call to initialize its branch-and-bound specific data.
6977 *
6978 * @subsection BENDERSCUTEXITSOL
6979 *
6980 * The BENDERSCUTEXITSOL callback is executed before the branch-and-bound process is freed. The Benders' decomposition
6981 * implementation should use this call to clean up its branch-and-bound data.
6982 *
6983 */
6984/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
6985
6986/**@page CONF How to use conflict analysis
6987 *
6988 * Conflict analysis is a way to automatically use the information obtained from infeasible nodes
6989 * in the branch-and-bound tree.
6990 *
6991 * Once a node is declared infeasible, SCIP automatically tries to infer a constraint that explains the reason for the
6992 * infeasibility, in order to avoid similar situations later in the search. This explanation essentially consists of a
6993 * constraint stating that at least one of its variables should have a bound different from the current infeasible node,
6994 * because the current setting led to infeasibility. Clearly, all variables that are fixed in the current infeasible
6995 * node would yield such a constraint (since this leads to infeasibility). The key point rather is to infer a "small"
6996 * constraint that does the same job. SCIP handles this by several heuristics. For this, SCIP sets up a
6997 * so-called (directed) conflict graph. The nodes in this graph correspond to bound changes of variables and an arc (@a
6998 * 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
6999 * will have several ingoing arcs which represent all bound changes that have been used to infer (propagate) the bound
7000 * change in question. The graph also contains source nodes for each bound that has been changed during branching and an
7001 * artificial target node representing the conflict, i.e., the infeasibility. Essentially, SCIP heuristically constructs
7002 * a cut in this graph that involves few "branching nodes". For details on the techniques that SCIP uses,
7003 * we refer to the paper @par
7004 * Tobias Achterberg, Conflict Analysis in Mixed Integer Programming@n
7005 * Discrete Optimization, 4, 4-20 (2007)
7006 *
7007 * For conflict analysis to work well, the author of a \ref CONS "Constraint Handler" or a
7008 * \ref PROP "Propagator" has to implement three kinds of functionality:
7009 *
7010 * -# If one detects infeasibility, one should initiate conflict analysis, see \ref INITCONFS "below".
7011 * -# During propagation, one should call the right functions to fix variables.
7012 * -# One should implement the <em>so-called reverse propagation</em>.
7013 *
7014 * If this functionality is not implemented, SCIP will still work correctly, but cannot use the information of the constraint
7015 * handler or the propagator for conflict analysis. In this case, each bound reduction performed by the constraint
7016 * handler/propagator will be treated as if it had been a branching decision.
7017 *
7018 * @section INITCONFS Initiating Conflict Analysis
7019 *
7020 * If one detects infeasibility within propagation, one should do the following:
7021 * -# Call SCIPinitConflictAnalysis().
7022 * -# Inform SCIP about the variable bounds that are the reason for the detection of infeasibility
7023 * via the functions SCIPaddConflictLb(), SCIPaddConflictUb(), SCIPaddConflictBd(), or
7024 * SCIPaddConflictBinvar(). If there is more than one valid explanation of infeasibility, either one can be used.
7025 * Typically, smaller explanations tend to be better.
7026 * -# Call SCIPanalyzeConflict() from a propagator or SCIPanalyzeConflictCons() from a constraint
7027 * handler.
7028 *
7029 * This functionality allows SCIP to set up the conflict graph and perform a conflict analysis.
7030 *
7031 * @section Propagation
7032 *
7033 * When propagating variable domains, SCIP needs to be informed that the deduced variable bounds should be
7034 * used in conflict analysis. This can be done by the functions SCIPinferVarLbCons(),
7035 * SCIPinferVarUbCons(), and SCIPinferBinvarCons() for constraint handlers and SCIPinferVarLbProp(),
7036 * SCIPinferVarUbProp(), and SCIPinferBinvarProp() for propagators. You can pass one integer of
7037 * information that should indicate the reason of the propagation and can be used in reverse
7038 * propagation, see the next section.
7039 *
7040 * @section RESPROP Reverse Propagation
7041 *
7042 * Reverse Propagation is used to build up the conflict graph. Essentially, it provides an algorithm to detect the arcs
7043 * leading to a node in the conflict graph, i.e., the bound changes responsible for the new bound change deduced during
7044 * propagation. Reverse Propagation needs to be implemented in the RESPROP callback functions of
7045 * \ref CONSRESPROP "constraint handlers" or \ref PROPRESPROP "propagators".
7046 * These callbacks receive the following information: the variable which is under investigation (@p
7047 * infervar), the corresponding bound change (@p bdchgidx, @p boundtype), and the integer (@p inferinfo) that has been
7048 * supplied during propagation.
7049 *
7050 * One can use SCIPvarGetUbAtIndex() or SCIPvarGetLbAtIndex() to detect the bounds before or after the propagation that
7051 * should be investigated. Then the bounds that were involved should be passed to SCIP via SCIPaddConflictLb() and
7052 * SCIPaddConflictUb(). If there is more than one valid explanation of infeasibility, either one can be used.
7053 * Typically, smaller explanations tend to be better.
7054 *
7055 * Details and (more) examples are given in Sections @ref CONSRESPROP and @ref PROPRESPROP.
7056 *
7057 *
7058 * @section Example
7059 *
7060 * Consider the constraint handler @p cons_linearordering.c in the
7061 * \ref LOP_MAIN "linear ordering example"
7062 * (see @p example/LOP directory). This constraint handler propagates the equations \f$x_{ij} + x_{ji} =
7063 * 1\f$ and triangle inequalities \f$x_{ij} + x_{jk} + x_{ki} \leq 2\f$.
7064 *
7065 * When propagating the equation and <code>vars[i][j]</code> is fixed to 1, the constraint handler uses
7066 * \code
7067 * SCIP_CALL( SCIPinferBinvarCons(scip, vars[j][i], FALSE, cons, i*n + j, &infeasible, &tightened) );
7068 * \endcode
7069 * Thus, variable <code>vars[j][i]</code> is fixed to 0 (@p FALSE), and it passes <code>i*n + j </code> as @p inferinfo.
7070 *
7071 * When it propagates the triangle inequality and both <code>vars[i][j]</code> and <code>vars[j][k]</code>
7072 * are fixed to 1, the constraint handler uses
7073 * \code
7074 * SCIP_CALL( SCIPinferBinvarCons(scip, vars[k][i], FALSE, cons, n*n + i*n*n + j*n + k, &infeasible, &tightened) );
7075 * \endcode
7076 * 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
7077 * passed as <code>inferinfo</code>.
7078 *
7079 * In reverse propagation, the two cases can be distinguished by @p inferinfo: if it is less than @p n*n,
7080 * we deal with an equation, otherwise with a triangle inequality. The constraint handler can then extract the
7081 * indices @p i, @p j (and @p k in the second case) from inferinfo.
7082 *
7083 * In the first case, it has to distinguish whether <code>vars[i][j]</code> is fixed to 0 or 1 &ndash;
7084 * by calling SCIPaddConflictLb()
7085 * or SCIPaddConflictUb(), respectively, with variable <code>vars[j][i]</code>. In the second case, it is clear that the only
7086 * 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>
7087 * are fixed to 1. It then calls
7088 * SCIPaddConflictLb() for both <code>vars[k][i]</code> and <code>vars[j][k]</code>.
7089 */
7090
7091/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7092
7093/**@page REOPT How to use reoptimization
7094 *
7095 * The reoptimization feature of SCIP can be used to solve a sequence of optimization problems \f$(P_{i})_{i \in I}\f$ with
7096 * \f[
7097 * (P_i) \quad \min \{ c_i^T x \;|\; A^ix \geq b^i,\; x_{j} \in \mathbb{Z}\;\forall j \in \mathcal{I} \}
7098 * \f]
7099 * 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
7100 * function changes. To use reoptimization the user has to change the parameter <code>reoptimization/enable</code> to
7101 * <code>TRUE</code> before the solving process of the first problem of the sequence starts, i.e., in stage
7102 * <code>SCIP_STAGE_INIT</code> or <code>SCIP_STAGE_PROBLEM</code>. This can be done via the interactive shell or by
7103 * calling SCIPenableReoptimization(). In both cases SCIP changes some parameters and fixes them:
7104 * -# disable conflict analysis based on dual information
7105 * -# set the limit <code>maxorigsol</code> of stored solutions to zero because this is handled by a special solution tree provided
7106 * by the reoptimization feature itself
7107 * -# disable restarts (<code>presolving/maxrestarts = 0</code>)
7108 * -# disable multi-aggegations (<code>presolving/donotmultaggr = TRUE</code>)
7109 * -# disable dual reductions within presolvers and propagators (<code>misc/allowdualreds = FALSE</code>)
7110 * -# disable propagation with current cutoff bound (<code>misc/allowobjprop = FALSE</code>)
7111 *
7112 * In contrast to the presolving and propagating methods that are using dual information, performing strong branching is
7113 * allowed. The bound tightenings resulting from strong branching are handeled in a special way. After changing the objective
7114 * function and solving the modified problem the feasible region that was pruned by strong branching will be reconstructed
7115 * within the tree.
7116 *
7117 * If the reoptimization feature is enabled SCIP tries to reuse the search tree, especially the search frontier at the end
7118 * of the solving process, to speed up the solving process of the following problems. Therefore, the current release
7119 * provides the branching rule <code>branch_nodereopt</code> to reconstruct the tree. SCIP triggers a restart of the
7120 * reoptimization, i.e., solving the problem from scratch, if
7121 *
7122 * -# the stored search tree is too large,
7123 * -# the objective functions changed too much, or
7124 * -# the last \f$n\f$ optimal solution are updated solution of previous runs.
7125 *
7126 * The thresholds to trigger a restart can be set by the user:
7127 *
7128 * -# <code>reoptimization/maxsavednodes</code>
7129 * -# <code>reoptimization/delay</code>
7130 * -# <code>reoptimization/forceheurrestart</code>
7131 *
7132 * Before SCIP discards all the stored information and solves the problem from scratch it tries to compress the search
7133 * tree. Therefore, the current release provides compression heuristics that try to find a good and much smaller
7134 * representation of the current search tree.
7135 *
7136 * After a problem in the sequence of optimization problems was solved, the objective function can be changed in two ways:
7137 * -# Using the provided reader <code>reader_diff</code> the objective function can be changed via using the interactive
7138 * shell
7139 * \code
7140 * SCIP> read new_obj.diff
7141 * \endcode
7142 * or by calling SCIPreadDiff().
7143 * -# The objective function can be changed within the code. Therefore, the transformed problem needs to be freed by
7144 * calling SCIPfreeReoptSolve(). Afterwards, the new objective function can be installed by calling
7145 * SCIPchgReoptObjective().
7146 *
7147 * After changing the objective function the modified problem can be solved as usal.
7148 *
7149 * \note Currently, the compression heuristics used between two successive reoptimization runs only support pure binary
7150 * and mixed binary programs.
7151 *
7152 * For more information on reoptimization we refer to@par
7153 * Jakob Witzig@n
7154 * Reoptimization Techniques in MIP Solvers@n
7155 * Master's Thesis, Technical University of Berlin, 2014.
7156 */
7157
7158/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7159
7160/**@page CONCSCIP How to use the concurrent solving mode
7161 *
7162 * @section Overview
7163 *
7164 * In \SCIP 4.0 a new feature has been added that allows to run multiple \SCIP instances with different settings
7165 * on one problem in parallel. To use this feature \SCIP has to be compiled with an additional make option to
7166 * enable the threading functionality (e.g. TPI=tny, see \ref MAKE).
7167 * Then, a concurrent solve can be started by using the <code>concurrentopt</code> command instead of the <code>optimize</code> command
7168 * in the \SCIP shell, or by calling the interface function SCIPsolveParallel().
7169 * To configure the behavior of the concurrent solving mode there are new parameters in the category <code>concurrent/</code>
7170 * and <code>parallel/</code> which will be explained here shortly.
7171 *
7172 * @section CONTROLNTHREADS Controlling the number of threads
7173 *
7174 * The parameters <code>parallel/maxnthreads</code> and <code>parallel/minnthreads</code> can be used to configure the number of threads
7175 * that sould be used for solving. \SCIP will try to use the configured maximum number of threads. If the
7176 * problem that is currently read is too large \SCIP will automatically use fewer threads, but never
7177 * go below the configured minimum number of threads.
7178 *
7179 * @section USEEMPHSETTINGS Using emphasis settings
7180 *
7181 * The parameters <code>concurrent/scip.../prefprio</code> configure which concurrent solvers should be used.
7182 * The concurrent solver <code>scip</code> will use the same settings as the \SCIP instance configured by the user.
7183 * The other concurrent solvers, e.g. <code>scip-feas</code>, will load the corresponding emphasis setting.
7184 * The behavior of the prefprio parameter is as follows: If it is set to 1.0 for <code>scip-feas</code> and
7185 * <code>scip-opti</code>, and to 0.0 for every other concurrent solver, then the threads will be evenly
7186 * 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
7187 * 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
7188 * and the latter will use 3 threads of the 4 available threads.
7189 *
7190 * @section CUSTOMCONCSOLVERS Running custom solvers
7191 *
7192 * To use custom settings for the concurrent solvers there is the parameter <code>concurrent/paramsetprefix</code>. If custom parameters
7193 * 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).
7194 * The parameter settings must be named after the concurrent solvers, e.g. if only the concurrent solver <code>scip</code> is used
7195 * 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
7196 * starts at one for each of them, e.g. <code>scip-1</code> and <code>scip-feas-1</code>.
7197 */
7198
7199/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7200
7201/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7202
7203/**@page DECOMP How to provide a problem decomposition
7204 *
7205 * Most mixed-integer programs have sparse constraint matrices in the sense that most columns and rows have only very few nonzero entries,
7206 * maybe except for a few outlier columns/rows with many nonzeros.
7207 * 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
7208 * columns, but are otherwise independent.
7209 * The special case of completely independent subproblems (with no linking rows and columns), for example, can be solved by solving
7210 * the much smaller subproblems and concatenating their optimal solutions.
7211 * This case has already been integrated into SCIP as a successful presolving technique (see @ref cons_components.c).
7212 * Another use of decomposition within SCIP is the @ref BENDDECF "Benders Decomposition framework".
7213 *
7214 * Since SCIP 7.0, it is easier to pass user decompositions to SCIP that can be used within Benders decomposition or by user algorithms.
7215 * This page introduces the struct SCIP_DECOMP and gives examples how to create and use it.
7216 *
7217 * @section DECOMP_OVERVIEW Overview
7218 *
7219 * In the following, we present decompositions of mixed-integer programs. However, the generalization to Constraint Integer Programs is straightforward.
7220 *
7221 * 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,
7222 *
7223 * \f[
7224 * 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}})
7225 * \f]
7226 * 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$.
7227 * 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.
7228 * In other words, the inequality system \f$A x \geq b\f$ can be rewritten
7229 * with respect to a decomposition \f$\mathcal{D}\f$ by a suitable permutation of the rows
7230 * and columns of \f$A\f$ as equivalent system
7231 * \f[
7232 * \left(
7233 * \begin{matrix}
7234 * A_{[D^{\text{row}}_{1},D^{\text{col}}_{1}]} &
7235 * 0 &
7236 * \cdots &
7237 * 0 &
7238 * A_{[D^{\text{row}}_{1},L^{\text{col}}]}\\
7239 * 0 &
7240 * A_{[D^{\text{row}}_{2},D^{\text{col}}_{2}]} &
7241 * 0 &
7242 * 0 &
7243 * A_{[D^{\text{row}}_{2},L^{\text{col}}]}\\
7244 * \vdots &
7245 * 0 &
7246 * \ddots &
7247 * 0 &
7248 * \vdots\\
7249 * 0 &
7250 * \cdots &
7251 * 0 &
7252 * A_{[D^{\text{row}}_{k},D^{\text{col}}_{k}]} &
7253 * A_{[D^{\text{row}}_{k},L^{\text{col}}]}\\
7254 * A_{[L^{\text{row}},D^{\text{col}}_{1}]} &
7255 * A_{[L^{\text{row}},D^{\text{col}}_{2}]} &
7256 * \cdots &
7257 * A_{[L^{\text{row}},D^{\text{col}}_{k}]} &
7258 * A_{[L^{\text{row}},L^{\text{col}}]}
7259 * \end{matrix}
7260 * \right)
7261 * \left(
7262 * \begin{matrix}
7263 * x_{[D^{\text{col}}_{1}]}\\
7264 * x_{[D^{\text{col}}_{2}]}\\
7265 * \vdots\\
7266 * x_{[D^{\text{col}}_{k}]}\\
7267 * x_{[L^{\text{col}}]}
7268 * \end{matrix}
7269 * \right)
7270 * \geq
7271 * \left(
7272 * \begin{matrix}
7273 * b_{[D^{\text{row}}_{1}]}\\
7274 * b_{[D^{\text{row}}_{2}]}\\
7275 * \vdots\\
7276 * b_{[D^{\text{row}}_{k}]}\\
7277 * b_{[L^{\text{row}}]}
7278 * \end{matrix}
7279 * \right)
7280 * % A= \left(\begin{matrix}4&8&\frac{1}{2}\\\frac{3}{2}&4&1\\1&3&7\end{matrix}\right)
7281 * \f]
7282 * where we use the short hand syntax \f$A_{[I,J]}\f$ to denote
7283 * the \f$|I|\f$-by-\f$|J|\f$ submatrix that arises from the deletion of all entries
7284 * from \f$A\f$ except for rows \f$I\f$ and columns \f$J\f$,
7285 * for nonempty row
7286 * and column subsets \f$I\subseteq\{1,\dots,m\}\f$ and \f$J\subseteq\{1,\dots,n\}\f$.
7287 *
7288 *
7289 * @section DECOMP_USING Using a decomposition
7290 *
7291 * After passing one or more decompositions, see below, one can access all available decompositions with SCIPgetDecomps().
7292 * The labels can be obtained by calling SCIPdecompGetVarsLabels() and SCIPdecompGetConsLabels().
7293 * If some variables/constraints are not labeled, these methods will mark them as linking variables/constraints.
7294 * There are several methods to get more information about one decomposition, see @ref DecompMethods.
7295 *
7296 * A decomposition can be used to split the problem into several subproblems which, in general, are easier to solve.
7297 * For \f$q \in \{1,\dots,k\}\f$ the system
7298 * \f[
7299 * A_{[D^{\text{row}}_{q},D^{\text{col}}_{q}]}\; x_{[D^{\text{col}}_{q}]} \geq b_{[D^{\text{row}}_{q}]}
7300 * \f]
7301 * is part of subproblem \f$q\f$, the handling of the linking variables/constraints depends on the chosen application context.
7302 * For example, in the heuristic @ref heur_padm.c several smaller subproblems are solved multiple times to get a feasible solution.
7303 * Also the @ref BENDDECF "Benders' decomposition framework" was extended with release 7.0 to use user decompositions.
7304 *
7305 * @section DECOMP_CREATION Creation via SCIP-API
7306 *
7307 * There are two different ways to provide a decomposition in SCIP.
7308 * It can be created with the SCIP-API or it can be read from a file.
7309 *
7310 * To create it with the API, the user must first create a decomposition with SCIPcreateDecomp() specifying
7311 * whether the decomposition belongs to the original or transformed problem and the number of blocks.
7312 * Then the variables and constraints can be assigned to one block or to the linking rows/columns by calling
7313 * SCIPdecompSetVarsLabels() and SCIPdecompSetConsLabels(), respectively.
7314 * To complete the decomposition or to ensure that it is internally consistent, SCIPcomputeDecompVarsLabels() or
7315 * SCIPcomputeDecompConsLabels() can be called.
7316 * Note that SCIPcomputeDecompVarsLabels() will ignore the existing variable labels and computes again the labels based on the constraint labels only;
7317 * SCIPcomputeDecompConsLabels() works in the same way and ignores the existing constraint labels.
7318 *
7319 * After the decomposition has been successfully created, it can be saved for later use in the DecompStore using SCIPaddDecomp().
7320 * Access to all decompositions in the DecompStore is possible with SCIPgetDecomps().
7321 *
7322 * @section DECOMP_READDEC Reading a decomposition from a file
7323 *
7324 * Alternatively, after a problem has been read, a related decomposition can be read from a dec-file.
7325 * Please refer to the @ref reader_dec.h "DEC file reader" for further information about the required file format.
7326 * 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.
7327 *
7328 * @section DECOMP_BENDERS Use for Benders
7329 *
7330 * 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.
7331 * With this setting, the variable's labeling takes place giving precedence to its presence in linking constraints over its presence in named blocks.
7332 *
7333 * @section DECOMP_TRANS Decomposition after problem transformation
7334 *
7335 * As the problem's constraints are constantly changing, or possibly deleted, during presolving, the constraints' labeling must be triggered again.
7336 * Therefore, SCIP automatically transforms all user decompositions at the beginning of the root node based on the variables' labels.
7337 *
7338 * @section DECOMP_STATS Decomposition statistics
7339 *
7340 * Further useful measures and statistics about the decomposition are computed within SCIPcomputeDecompStats().
7341 * When the labeling process is concluded, the following measures are computed and printed:
7342 * - the number of blocks;
7343 * - the number of linking variables and linking constraints;
7344 * - the size of the largest as well as the smallest block;
7345 * - the area score:
7346 * This score is also used by GCG to rank decompositions during the automatic detection procedure.
7347 * For a decomposition
7348 * \f$\mathcal{D}=(D^{\text{row}},D^{\text{col}})\f$,
7349 * the area score is defined as
7350 * \f[
7351 * \text{areascore}(\mathcal{D}) = 1 - \frac{ \sum_{q=1}^k \lvert D^{\text{row}}_{q} \rvert
7352 * \lvert D^{\text{col}}_{q} \rvert + n\lvert L^{\text{row}} \rvert + m\lvert L^{\text{col}} \rvert -
7353 * \lvert L^{\text{row}} \rvert \lvert L^{\text{col}} \rvert }{mn}
7354 * \enspace.
7355 * \f]
7356 * In the case of a mixed-integer program, the area score intuitively measures the coverage of the rearranged matrix by 0's.
7357 * Decompositions with few linking variables and/or constraints and many small blocks \f$A_{[D^{\text{row}}_{q},D^{\text{col}}_{q}]}\f$
7358 * will have an area score close to \f$1\f$, whereas coarse decompositions of a matrix have smaller area scores.
7359 * The trivial decomposition with a single block has the worst possible area score of 0.
7360 * - the modularity:
7361 * This measure is used to assess the quality of the community structure within a decomposition.
7362 * The modularity of the decomposition is computed as follows:
7363 * \f[
7364 * \begin{aligned}
7365 * \sum_{q=1}^{k} \dfrac{e_{q}}{m} \left(1-\dfrac{e_{q}}{m}\right),
7366 * \end{aligned}
7367 * \f]
7368 * 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.
7369 * The presence of an inner edge is identified through the presence of a variable in a constraint,
7370 * both—the variable and the constraint—belonging to the same block.
7371 * - 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.
7372 * Note that the linking constraints are intentionally skipped in this computation.
7373 * \f$ G = (V,E) \f$ denotes a block graph, with vertex set \f$V\f$ and edge set \f$E\f$.
7374 * Each vertex in the graph represents a block in the decomposition; \f$V = \{v_{1},\dots,v_{k}\}\f$.
7375 * 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$
7376 * 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$.
7377 * From the constructed graph, the number of edges, articulation points and connected components are computed, together with the maximum and minimum degree.
7378 * Note that building the block graph can become computationally expensive with large and dense decompositions.
7379 * Thus, it is possible through a user parameter <code>decomposition/maxgraphedge</code> to define a maximum edge limit.
7380 * 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.
7381 *
7382 */
7383
7384/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7385
7386
7387/**@page BENDDECF How to use the Benders' decomposition framework
7388 *
7389 * Benders' decomposition is a very popular mathematical programming technique that is applied to solve structured
7390 * problems. Problems that display a block diagonal structure are particularly amenable to the application of Benders'
7391 * decomposition. In a purely mixed-integer linear setting, such problems are given by
7392 *
7393 * \f[
7394 * \begin{array}[t]{rllclcl}
7395 * \min & \displaystyle & c^{T}x & + & d^{T}y \\
7396 * & \\
7397 * \text{subject to} & \displaystyle & Ax & & & = & b \\
7398 * & \\
7399 * & \displaystyle & Tx & + & Hy & = & h \\
7400 * & \\
7401 * & & x & & & \in & \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
7402 * & & & & y & \in & \mathbb{R}^{m} \\
7403 * \end{array}
7404 * \f]
7405 *
7406 * The variables \f$x\f$ and \f$y\f$ are described as the first and second stage variables respectively. In the
7407 * classical use of Benders' decomposition, it is a requirement that the all second stage variables are continuous.
7408 * Extensions to the classical Benders' decomposition approach have permitted the use of more general second stage
7409 * problems.
7410 *
7411 * The application of Benders' decomposition to the above problem results in a subproblem, given by
7412 *
7413 * \f[
7414 * \begin{array}[t]{rll}
7415 * \min & \displaystyle & d^{T}y \\
7416 * & \\
7417 * \text{subject to} & \displaystyle & Hy = h - T\bar{x} \\
7418 * & \\
7419 * & & y \in \mathbb{R}^{m} \\
7420 * \end{array}
7421 * \f]
7422 *
7423 * where \f$\bar{x}\f$ is a solution vector of the first stage variables. As such, the subproblem is a problem only in
7424 * \f$y\f$. The dual solution to the subproblem, either an extreme point or extreme ray, is used to generate cuts that
7425 * are added to the master problem. Let \f$\lambda\f$ be the vector of dual variables associated with the set of
7426 * constraints from the subproblem. If, for a given \f$\bar{x}\f$, the subproblem is infeasible, then \f$\lambda\f$
7427 * corresponds to a dual ray and is used to produce the cut
7428 *
7429 * \f[
7430 * 0 \geq \lambda(h - Tx)
7431 * \f]
7432 *
7433 * which eliminates \f$\bar{x}\f$ from the master problem. If, for a given \f$\bar{x}\f$, the subproblem is feasible,
7434 * then \f$\lambda\f$ corresponds to a dual extreme point and is used to produce the cut
7435 *
7436 * \f[
7437 * \varphi \geq \lambda(h - Tx)
7438 * \f]
7439 *
7440 * where \f$\varphi\f$ is an auxiliary variable added to the master problem as an underestimator of the optimal
7441 * subproblem objective function value.
7442 *
7443 * Given \f$\Omega^{p}\f$ and \f$\Omega^{r}\f$ as the sets of dual extreme points and rays of the subproblem,
7444 * respectively, the Benders' decomposition master problem is given by
7445 *
7446 * \f[
7447 * \begin{array}[t]{rll}
7448 * \min & \displaystyle & c^{T}x + \varphi \\
7449 * & \\
7450 * \text{subject to} & \displaystyle & Ax = b \\
7451 * & \\
7452 * & \displaystyle & \varphi \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r}\\
7453 * & \\
7454 * & \displaystyle & 0 \geq \lambda(h - Tx) \quad \forall \lambda \in \Omega^{r} \\
7455 * & \\
7456 * & & x \in \mathbb{Z}^{p}\times\mathbb{R}^{n - p} \\
7457 * & & \varphi \in \mathbb{R} \\
7458 * \end{array}
7459 * \f]
7460 *
7461 * @section BENDERFRAMEWORK Overview
7462 *
7463 * In \SCIP 6.0 a Benders' decomposition framework has been implemented.
7464 *
7465 * The current framework can be used to handle a Benders Decomposition of CIPs of the form
7466 *
7467 * \f[
7468 * \begin{array}[t]{rllclcl}
7469 * \min & \displaystyle & c^{T}x & + & d^{T}y \\
7470 * \text{subject to} & \displaystyle & g(x & , & y) & \in & [\ell,u] \\
7471 * & & x & & & \in & X \\
7472 * & & & & y & \in & Y \\
7473 * \end{array}
7474 * \f]
7475 * when either
7476 * - 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
7477 * - the first stage variables are of binary type: \f$ X \subseteq \{0,1\}^n \f$.
7478 *
7479 * This framework can be used in four different
7480 * ways: inputting an instance in the SMPS file format, using the default Benders' decomposition implementation
7481 * (see src/scip/benders_default.c), implementing a custom Benders' decomposition plugin (see \ref BENDER), or by using
7482 * the Benders' decomposition mode of GCG.
7483 * An overview of how to use each of these methods will be provided in this section.
7484 *
7485 * @section BENDERSSMPS Inputting an instance in the SMPS file format.
7486 *
7487 * As part of the Benders' decomposition framework development, a reader for instances in the SMPS file format has been
7488 * implemented (see src/scip/reader_smps.c). The details regarding the SMPS file format can be found at:
7489 *
7490 * Birge, J. R.; Dempster, M. A.; Gassmann, H. I.; Gunn, E.; King, A. J. & Wallace, S. W.
7491 * A standard input format for multiperiod stochastic linear programs
7492 * IIASA, Laxenburg, Austria, WP-87-118, 1987
7493 *
7494 * In brief, the SMPS file format involves three different files:
7495 * - A core file (.cor): a problem instance in MPS format that is the core problem of a stochastic program.
7496 * - A time file (.tim): partitions the variables and constraints into the different stages of the stochastic program
7497 * - A stochastic file (.sto): describes the scenarios for each stage.
7498 *
7499 * The STO reader (see src/scip/reader_sto.c) constructs the stochastic program using the information from the core and
7500 * time files. By default, the STO reader will construct the deterministic equivalent of the stochastic program. A
7501 * parameter is provided "reading/sto/usebenders" that will inform the STO reader to apply Benders' decomposition to the
7502 * input stochastic program.
7503 *
7504 * @section BENDERSDEFAULT Using the default Benders' decomposition plugin.
7505 *
7506 * A default implementation of a Benders' decomposition plugin has been included in \SCIP 6.0 (see
7507 * src/scip/benders_default.c). In order to use the default plugin, the user must create SCIP instances of the master
7508 * problem and subproblems. The subproblems must also contain a copy of the master problem variables, since these are
7509 * fixed to the master problem solution values during the subproblem solving loop. These SCIP instances for the master
7510 * and subproblems are passed to the default plugin by calling SCIPcreateBendersDefault().
7511 *
7512 * The mapping between the master and subproblem variables is performed automatically. The default solving and cut
7513 * generation methods are applied to solve the input problem. It is important to note that the mapping between the
7514 * master and subproblem variables relies on the variable names. The variables of the subproblem corresponding to
7515 * master problem variables must have the same name in both problems.
7516 *
7517 * The CAP (stochastic capacitated facility location problem) example demonstrates the use of the default Benders'
7518 * decomposition implementation within a project.
7519 *
7520 * @section BENDERSCUSTOM Implementing a custom Benders' decomposition implementation.
7521 *
7522 * A custom Benders' decomposition requires the implementation of a Benders' decomposition plugin. The key aspects for
7523 * implementing a custom Benders' decomposition plugin are explained in \ref BENDER.
7524 *
7525 * @section BENDERSGCG Using the Benders' decomposition mode of GCG
7526 *
7527 * In GCG 3.0, a Benders' decomposition mode has been implemented. This mode takes the decomposition found by the
7528 * detection schemes of GCG and applies Benders' decomposition. Using GCG it is possible to apply Benders' decomposition
7529 * to general problem without having to manually construct the decompositions.
7530 *
7531 */
7532
7533/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7534
7535/**@page PROBINGDIVING How to use probing and diving mode
7536 *
7537 * SCIP contains two methods to perform a temporary dive in the branch-and-bound tree: the diving mode and the probing mode.
7538 * Both methods enable the modification of variable bounds, addition of new constraints, or adjustments to the objective function.
7539 * 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.
7540 * 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.
7541 *
7542 * 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.
7543 * 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].
7544 * To reset all changes, the respective mode needs to be ended by calling SCIPendDive() and SCIPendProbing(), respectively.
7545 *
7546 * 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.
7547 * 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.
7548 * Similarly, the function SCIPpropagateProbing() might find globally valid bound changes, which are added to the main SCIP and considered in the subsequent solving process.
7549 * Another way to leverage insights found during probing or diving is to update pseudo costs during both modes, helping make better branching decisions.
7550 * This is controlled by setting the parameter "divingpscosts" to TRUE, which is done in the default settings of SCIP.
7551 * 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.
7552 * In some cases, such as when dealing with a numerically difficult instance, this might lead to a different LP state.
7553 * Finally, during probing, global variable statistics can be collected by calling SCIPenableVarHistory() after starting probing.
7554 * 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.
7555 *
7556 */
7557/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7558
7559/**@page OBJ Creating, capturing, releasing, and adding data objects
7560 *
7561 * Data objects (variables, constraints, rows, ... ) are subject to reference counting
7562 * to avoid expensive copying operations. This concept is similar to smart pointers.
7563 * Creating such an object (e.g., by calling SCIPcreateVar()) will set the
7564 * reference counter to one. Capturing an object (e.g., by calling SCIPcaptureVar()) increases the reference counter,
7565 * releasing it (e.g., by calling SCIPreleaseVar()) decreases the counter. If the reference counter gets zero, the
7566 * object will be destroyed automatically.
7567 *
7568 * Remember that a created data object is automatically captured. If the user
7569 * doesn't need the object anymore, (s)he has to call the object's release method.
7570 *
7571 * When a data object is added to SCIP (e.g., by calling SCIPaddVar()) , it is captured again, such that a
7572 * release call does not destroy the object. If SCIP doesn't need the object
7573 * anymore, it is automatically released.
7574 *
7575 * E.g., if the user calls
7576 * \code
7577 * SCIPcreateVar(); // reference counter 1
7578 * SCIPaddVar(); // reference counter 2
7579 * SCIPreleaseVar(); // reference counter 1
7580 * \endcode
7581 * the reference counter will be 1 afterwards, and the variable will be destroyed, if SCIP frees the problem.
7582 * If the user wants to use this variable, e.g. for extracting statistics after SCIP was finished, the user must not call
7583 * SCIPreleaseVar() right after adding the variable, but before terminating the program.
7584 */
7585
7586/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7587
7588/**@page PARAM How to add additional user parameters
7589 *
7590 * Users may add their own parameters to SCIP by calling SCIPaddXyzParam(). Using
7591 * this method, there are two possibilities for where to store the actual parameter value:
7592 * - If the given valueptr is NULL, SCIP stores the parameter value internally, and
7593 * the user can only access the value with the SCIPgetXyzParam() and
7594 * SCIPsetXyzParam() calls.
7595 * - If the given valueptr is not NULL, SCIP stores the parameter value at the given
7596 * address, and the user can directly manipulate the value at this address.
7597 * (S)he has to be careful with memory management in string parameters: when the
7598 * SCIPaddStringParam() method is called, the given address must hold a char*
7599 * pointer with value NULL. The default value is then copied into this pointer,
7600 * allocating memory with BMSallocMemoryArray(). If the parameter is changed, the
7601 * old string is freed with BMSfreeMemoryArray() and the new one is copied to a new
7602 * memory area allocated with BMSallocMemoryArray(). When the parameter is freed,
7603 * the memory is freed with BMSfreeMemoryArray().
7604 * The user should not interfere with this internal memory management. Accessing
7605 * the string parameter through the given valueptr is okay as long as it does not
7606 * involve reallocating memory for the string.
7607 *
7608 * In some cases, it is necessary to keep track of changes in a parameter.
7609 * If this is the case, the user can define a method by the PARAMCHGD callback and use this method as
7610 * the @c paramchgd parameter of the @c SCIPaddXyzParam() method, also giving a pointer to the data, which is
7611 * needed in this method, as @c paramdata. If this method is not NULL, it is called every time
7612 * the value of the parameter is changed.
7613 */
7614
7615/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7616
7617/**@page MEMORY Using the memory functions of SCIP
7618 *
7619 * SCIP provides three ways for allocating memory:
7620 * -# <b>block memory:</b> efficient handling of memory blocks of similar small sizes
7621 * -# <b>buffer memory:</b> efficient handling of memory that needs to locally be allocated and freed
7622 * -# <b>standard memory:</b> access to standard malloc/free
7623 *
7624 * <em>Whenever possible, the first two should be used, because of reasons detailed below.</em>
7625 *
7626 * In the following, we provide a brief description of these methods. We refer the reader to the dissertation of Tobias
7627 * Achterberg for more details. We also present best practice models.
7628 *
7629 * @section MEMBACK Background
7630 *
7631 * The main goals for providing such particular methods are:
7632 * - <em>Accounting:</em> Using its own functions, SCIP knows the total size of memory allocated internally and can change its
7633 * behavior: for instance, it can change to "memory saving mode" (using depth first search (DFS) and possibly do a garbage
7634 * collection). It also allows for keeping a memory limit.
7635 * - <em>Speed:</em> SCIP often needs to allocate a very large number of small blocks of similar sizes (often powers of
7636 * two). Depending on the operating system and compiler, the methods implemented in SCIP can be faster, since blocks
7637 * of the same size are grouped together. Especially at the end of the 1990ies the standard malloc/free methods were
7638 * quite ineffective. The experiments of Tobias Achterberg in 2007 show a speed improvement of 11 % when using block
7639 * memory.
7640 * - <em>Efficiency:</em> Since blocks are groups in sizes, the blocks do not need to store their sizes within each
7641 * block. In comparison, standard malloc/free stores the size using one word for each memory chunk. The price to pay
7642 * is that one needs to pass the size to the methods that free a block. In any case, the methods in SCIP can save
7643 * memory. Moreover, buffer memory is stored in similar places and not spread out, which also might help cache.
7644 * - <em>Debugging:</em> All of the possibilities provide methods to detect memory leaks. Together with tools like
7645 * valgrind, this can be quite effective in avoiding such problems.
7646 *
7647 * @n
7648 * @section BLKMEM Block memory
7649 *
7650 * SCIP offers its own block memory handling, which allows efficient handling of smaller blocks of memory in cases in
7651 * which many blocks of the same (small) size appear. This is adequate for branch-and-cut codes in which small blocks
7652 * of the same size are allocated and freed very often (for data structures used to store rows or branch-and-bound
7653 * nodes). Actually, most blocks allocated within SCIP have small sizes like 8, 16, 30, 32, 64. The idea is simple:
7654 * There is a separate list of memory blocks for each interesting small size. When allocating memory, the list is
7655 * checked for a free spot in the list; if no such spot exists, the list is enlarged. Freeing just sets the block to be
7656 * available. Very large blocks are handled separately. See the dissertation of Tobias Achterberg for more details.
7657 *
7658 * One important comment is that freeing block memory requires the size of the block in order to find the right list.
7659 *
7660 * The most important functions are
7661 * - SCIPallocBlockMemory(), SCIPallocBlockMemoryArray() to allocate memory
7662 * - SCIPfreeBlockMemory(), SCIPfreeBlockMemoryArray() to free memory
7663 *
7664 * An example code is:
7665 * @refsnippet{tests/src/misc/snippets.c,SnippetArrayAllocAndFree}
7666 * @n
7667 *
7668 * @section BUFMEM Buffer memory
7669 *
7670 * @subsection BUFMEMSTD Standard Buffer Memory
7671 *
7672 * In addition to block memory, SCIP offers buffer memory. This should be used if memory is locally used within a
7673 * function and freed within the same function. For this purpose, SCIP has a list of memory buffers that are reused for
7674 * this purpose. In this way, a very efficient allocation/freeing is possible.
7675 *
7676 * Note that the buffers are organized in a stack, i.e., freeing buffers in reverse order of allocation is faster.
7677 *
7678 * The most important functions are
7679 * - SCIPallocBuffer(), SCIPallocBufferArray() to allocate memory,
7680 * - SCIPfreeBuffer(), SCIPfreeBufferArray() to free memory.
7681 *
7682 * @subsection BUFMEMCLEAN Clean Buffer Memory
7683 *
7684 * SCIP 3.2 introduced a new type of buffer memory, the <em>clean buffer</em>. It provides memory which is initialized to zero
7685 * and requires the user to reset the memory to zero before freeing it. This can be used at performance-critical
7686 * places where only few nonzeros are added to a dense array and removing these nonzeros individually is much faster
7687 * than clearing the whole array. Similar to the normal buffer array, the clean buffer should be used for temporary memory
7688 * allocated and freed within the same function.
7689 *
7690 * The most important functions are
7691 * - SCIPallocCleanBufferArray() to allocate memory,
7692 * - SCIPfreeCleanBufferArray() to free memory.
7693 *
7694 * @n
7695 * @section STDMEM Standard memory
7696 *
7697 * SCIP provides an access to the standard C functions @c malloc and @c free with the additional feature of tracking
7698 * memory in debug mode. In this way, memory leaks can be easily detected. This feature is automatically activated in
7699 * debug mode.
7700 *
7701 * The most important functions are
7702 * - SCIPallocMemory(), SCIPallocMemoryArray() to allocate memory,
7703 * - SCIPfreeMemory(), SCIPfreeMemoryArray() to free memory.
7704 *
7705 * @n
7706 * @section MEMBESTPRACTICE Best Practice of Using Memory Functions
7707 *
7708 * Since allocating and freeing memory is very crucial for the speed and memory consumption of a program, it is
7709 * important to keep the following notes and recommendations in mind.
7710 *
7711 * @subsection GEN General Notes
7712 *
7713 * The following holds for all three types of memory functions:
7714 * - In debug mode, the arguments are checked for overly large allocations (usually arising from a bug). Note that all
7715 * arguments are converted to unsigned values of type @c size_t, such that negative sizes are converted into very
7716 * large values.
7717 * - The functions always allocate at least one byte and return non-NULL pointers if memory is available. In particular,
7718 * freeing is always possible.
7719 * - The freeing methods set the pointer to the memory to NULL.
7720 * - Debugging can be supported by using the compiler flags @p NOBLKMEM=true, @p NOBUFMEM=true, @p NOBLKBUFMEM=true
7721 * that turn off the usage of block memory, buffer memory, as well as block and buffer memory, respectively. Since,
7722 * the internal block and buffer memory is freed at the end (leaving no memory leaks), turning them off allows tools
7723 * like valgrind to find memory leaks.
7724 * - Moreover, additional checks can be turned on by defining @p CHECKMEM in memory.c.
7725 *
7726 * @n
7727 * @subsection DOS Things to do ...
7728 *
7729 * - Use buffer memory if your memory chunk can be allocated and freed within the same function.
7730 * - Use buffer and block memory wherever possible, because of the reasons explained above.
7731 * - Free memory in the reverse order in which it was allocated! For block and buffer memory this @b significantly
7732 * speeds up the code.
7733 * - Use as few memory allocations/freeing operations as possible, since these functions take a significant amount of time.
7734 *
7735 * @n
7736 * @subsection DONTS Things to avoid ...
7737 *
7738 * - Avoid the usage of standard memory, since SCIP is unaware of the size used in such blocks.
7739 * - Avoid reallocation with only slightly increased size, rather use a geometrically growing
7740 * size allocation. SCIPcalcMemGrowSize() is one way to calculate new sizes.
7741 * - Be careful with buffer memory reallocation: For single buffers, the memory is reallocated (using malloc); since
7742 * the actual space might be larger than what was needed at allocation time, reallocation sometimes comes without
7743 * extra cost. Note that reallocating block memory in most cases implies moving memory arround.
7744 */
7745
7746/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7747
7748/**@page DEBUG Debugging
7749 *
7750 * If you need to debug your own code that uses SCIP, here are some tips and tricks:
7751 *
7752 * - Use <b>asserts</b> in your code to show preconditions for the parameters, invariants and postconditions.
7753 * Assertions are boolean expressions which inevitably have to evaluate to <code>TRUE</code>. Consider the
7754 * following example:
7755 *
7756 * @refsnippet{src/scip/cons_linear.c,SnippetDebugAssertions}
7757 *
7758 * As you can see, both pointers and integers are checked for valid values at the beginning of the
7759 * function <code>consCatchEvent()</code>. This is particularly important for, e.g., array indices like
7760 * the variable <code>pos</code> in this example, where using the <code>consdata->vars[pos]</code>
7761 * pointer could result in unexspected behaviour
7762 * if the asserted precondition on <code>pos</code> were not matched and <code>pos</code> were an arbitrary index
7763 * outside the array range.
7764 *
7765 * - In order to activate assertions, use the <b>Debug mode</b> by compiling SCIP via
7766 * \code
7767 * cmake -DCMAKE_BUILD_TYPE=Debug
7768 * \endcode
7769 * or the Makefile equivalent
7770 * \code
7771 * make OPT=dbg
7772 * \endcode and run the code. See \ref CMAKE and \ref MAKE for further information about compiler options for SCIP.
7773 * As a rule of thumb, Spending only little extra time on
7774 * asserting preconditions saves most of the time spent on debugging!
7775 *
7776 * - Turn on <b>additional debug output</b> by adding the line
7777 * \code
7778 * #define SCIP_DEBUG
7779 * \endcode
7780 * at the top of SCIP files you want to analyze. This will output messages included in the code using
7781 * <code>SCIPdebugMsg(scip, ...)</code> (or <code>SCIPdebugMessage()</code>), see \ref EXAMPLE_1.
7782 * We recommend to also use <code>SCIPdebugMsg(scip, ...)</code> in your own code for being able to activate
7783 * debug output in the same way.
7784 * - If available on your system, we recommend to use a debugger like <code>gdb</code>
7785 * to trace all function calls on the stack,
7786 * display values of certain expressions, manually break the running code, and so forth.
7787 * - If available on your system, you can use software like <a href="http://valgrind.org">valgrind</a> to check for uninitialized
7788 * values or segmentation faults.
7789 * - For checking the usage of SCIP memory, you can use
7790 * <code>SCIPprintMemoryDiagnostic()</code>. This outputs memory that is currently in use,
7791 * which can be useful after a <code>SCIPfree()</code> call.
7792 * - 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>
7793 * (or <code>make NOBLKBUFMEM=true</code> if you are using the Makefile system.
7794 * Also for the Makefile system, do not forget to clean your code before with <code>make OPT=... LPS=... clean</code>)
7795 * Only with that change, valgrind (or similar) reliably helps
7796 * to detect leaked memory.
7797 * - If your code cuts off a feasible solution, but you do not know which component is responsible,
7798 * you can use the debugging mechanism (see \ref EXAMPLE_2). Therefore, a given solution is read and it
7799 * is checked for every reduction, whether the solution will be pruned globally.
7800 *
7801 * @section EXAMPLE_1 How to activate debug messages
7802 * For example, if we include a <code>\#define SCIP_DEBUG</code> at the top of \ref heur_oneopt.c, recompile SCIP
7803 * in Debug mode, and run the SCIP interactive shell to solve p0033.mps from the
7804 * <a href="http://miplib2010.zib.de/miplib3/miplib.html">MIPLIB 3.0</a> , we get some output like:
7805 *
7806 * \include debugexamples/example1.txt
7807 *
7808 * @section EXAMPLE_2 How to add a debug solution
7809 *
7810 * Continuing the example above, we finish the solving process.
7811 * The optimal solution can now be written to a file:
7812 * \include debugexamples/example2_1.txt
7813 *
7814 * If we afterwards recompile SCIP with the additional compiler flag <code>cmake -DDEBUGSOL=on</code> (<code>make DEBUGSOL=true</code> in the Makefile system),
7815 * set the parameter <code>misc/debugsol = check/p0033.sol</code>, and run SCIP again it will output:
7816 * \include debugexamples/example2_2.txt
7817 * Further debug output would only appear, if the solution was cut off in the solving process.
7818 */
7819
7820/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7821
7822/**@page STAGES SCIP stages
7823 *
7824 * The SCIP object goes through different stages during the solving process, the transitions from one to the next are presented in the following diagram.
7825 * \image html stages.png
7826 * More exhaustively, the stages are:
7827 * \code
7828 * SCIP_STAGE_INIT = 0, /**< SCIP data structures are initialized, no problem exists
7829 * SCIP_STAGE_PROBLEM = 1, /**< the problem is being created and modified
7830 * SCIP_STAGE_TRANSFORMING = 2, /**< the problem is being transformed into solving data space
7831 * SCIP_STAGE_TRANSFORMED = 3, /**< the problem was transformed into solving data space
7832 * SCIP_STAGE_INITPRESOLVE = 4, /**< presolving is initialized
7833 * SCIP_STAGE_PRESOLVING = 5, /**< the problem is being presolved
7834 * SCIP_STAGE_EXITPRESOLVE = 6, /**< presolving is exited
7835 * SCIP_STAGE_PRESOLVED = 7, /**< the problem was presolved
7836 * SCIP_STAGE_INITSOLVE = 8, /**< the solving process data is being initialized
7837 * SCIP_STAGE_SOLVING = 9, /**< the problem is being solved
7838 * SCIP_STAGE_SOLVED = 10, /**< the problem was solved
7839 * SCIP_STAGE_EXITSOLVE = 11, /**< the solving process data is being freed
7840 * SCIP_STAGE_FREETRANS = 12, /**< the transformed problem is being freed
7841 * SCIP_STAGE_FREE = 13 /**< SCIP data structures are being freed
7842 * \endcode
7843 * Most functions can be called in a subset of the stages, this is then documented, a runtime check is often added and will throw a \ref SCIP_INVALIDCALL if the stage is not allowed.
7844 */
7845
7846/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7847
7848/**@page SRCORGA Organization of Source Code
7849 *
7850 * The SCIP source code has different types of files, distinguished by their naming style. The following list gives an overview of the most important file types and their purpose.
7851 *
7852 * @section SRCORGA_CORE SCIP core components
7853 *
7854 * - Each core component has an implementation with an internal API and a public API.
7855 * - The internal implementation should be in a file `<component>.c,h` and should not be included in the public API.
7856 * - Internal API functions usually do not take a `SCIP*` parameter, but a pointer to the component as first argument and pointers to internal structures like `SCIP_SET*` or `SCIP_STAT*`, where necessary.
7857 * - The name of internal API functions follows the style `SCIP<component><operation>...`, e.g., <code>SCIPvarCreateOriginal()</code> or <code>SCIPvarAddLocks()</code>.
7858 * - `pub_<component>.h` declares the functions of the public API that do not need a SCIP pointer.
7859 * Often, these are getter-functions.
7860 * For example, \ref pub_var.h contains public variable API functions.
7861 * - Functions in `pub_<component>.h` follow the same naming style as those in `<component>.h` and are used by the implementation of the internal API as well.
7862 * - `scip_<component>.h` declares the functions of the public API that need a SCIP instance (`SCIP*`), e.g., \ref scip_var.h for public variable manipulation functions.
7863 * Functions declared in `scip_<component>.h` are often thin wrappers that call the internal API functions from `<component>.h`.
7864 * These functions should follow the naming style `SCIP<operation><component>...`, e.g., <code>SCIPcreateVarOriginal()</code> or <code>SCIPaddVarLocks()</code>.
7865 * - To ensure functions of the public API being reachable in shared libraries, their declaration needs to contain the <code>SCIP_EXPORT</code> attribute.
7866 * - Public types (typedef's, enumerations) are defined in file `type_<component>.h`.
7867 * Type names follow the style `SCIP_<COMPONENT>...`.
7868 * - Structs that need to be accessed by several source files are defined in `struct_<component>.h`.
7869 * `struct_<component>.h` is usually included only by `<component>.c` and maybe `scip_<component>.c`.
7870 * Exceptions are due to manual inlining of functions via macros when compiling for optimized mode.
7871 * - All types, structs, and functions are documented with Doxygen-style comments.
7872 * The documentation of the implementation of a function must repeat the documentation of the function declaration exactly (for doxygen to treat them as identical).
7873 *
7874 * @section SRCORGA_PLUGINS Plugins
7875 * - Each plugin is defined in files `<type>_<name>.c,h`, e.g.,
7876 * \ref cons_knapsack.c implements the Knapsack constraint handler plugin and
7877 * \ref cons_knapsack.h declares its public API functions.
7878 * - Public types that belong to a plugin are declared in its header, `<type>_<name>.h`.
7879 * - API functions of plugins are named as `SCIP<operation>...<Name>`, e.g., <code>SCIPincludeConshdlrAnd()</code>, <code>SCIPcreateConsAnd()</code>, or <code>SCIPgetNVarsAnd()</code>.
7880 * - Plugins access only the public API.
7881 * - Plugins that need to be included by default should be registered in <code>src/scip/scipdefplugins.c</code>.
7882 */
7883
7884/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
7885
7886/**@page TEST How to run automated tests with SCIP
7887 *
7888 * SCIP comes along with a set of useful tools that allow to perform automated tests. The
7889 * following is a step-by-step guide from setting up the test environment for evaluation and
7890 * customization of test runs.
7891 *
7892 *
7893 * @section SETUP Setting up the test environment
7894 *
7895 * At first you should create a file listing all problem instances that should be part of the test.
7896 * This file has to be located in the the directory <code>scip/check/testset/</code>
7897 * and has to have the file extension <code>.test</code>, e.g., <code>testrun.test</code>,
7898 * in order to be found by the <code>scip/check/check.sh</code> script.
7899 * \n
7900 * All test problems can be listed in the <code>test</code>-file by a relative path,
7901 * e.g., <code>../../problems/instance1.lp</code> or absolute path, e.g., <code>/home/problems/instance2.mps</code>
7902 * in this file. Only one problem should be listed on every line (since the command <code>cat</code> is used to parse this file).
7903 * Note that these problems have to be readable for SCIP in order to solve them.
7904 * However, you can use different file formats.
7905 *
7906 * Optionally, you can provide a solution file in the <code>scip/check/testset/</code> directory containing
7907 * known information about the feasibility and the best known objective values for the test instances.
7908 * SCIP can use these values to verify the results. The file has to have the same basename as the
7909 * <code>.test</code>-file, i.e., in our case <code>testrun.solu</code>. One line can only contain
7910 * information about one test instance. A line has to start with the type of information given:
7911 *
7912 * - <code>=opt=</code> stating that a problem name with an optimal objective value follows
7913 * - <code>=best=</code> stating that a problem name with a best know objective value follows
7914 * - <code>=inf=</code> stating that a problem name follows which is infeasible
7915 *
7916 * With these information types you can encode for an instance named <code>instance1.lp</code> the following
7917 * information:
7918 * - The instance has a known optimal (objective) value of 10.
7919 * \code
7920 * =opt= instance1 10
7921 * \endcode
7922 * - The instance has a best known solution with objective value 15.
7923 * \code
7924 * =best= instance1 15
7925 * \endcode
7926 * - The instance is feasible (but has no objective function or we don't know a solution value)
7927 * \code
7928 * =feas= instance1
7929 * \endcode
7930 * - The instance is infeasible.
7931 * \code
7932 * =inf= instance1
7933 * \endcode
7934 *
7935 * If you don't know whether the instance is feasible or not (so the status is unknown),
7936 * you can omit the instance in the <code>solu</code>-file or write
7937 * \code
7938 * =unkn= instance1
7939 * \endcode
7940 *
7941 * <b>Note that in all lines the file extension of the file name is omitted.</b>
7942 * \n
7943 * See the files <code>scip/check/testset/short.test</code> and <code>scip/check/testset/short.solu</code>
7944 * for an example of a <code>test</code>-file and its corresponding <code>solu</code>-file.
7945 *
7946 *
7947 *
7948 * @section STARTING Starting a test run
7949 *
7950 *
7951 * \code
7952 * make TEST=testrun test
7953 * \endcode
7954 *
7955 * in the SCIP root directory. Note that <code>testrun</code> is exactly the basename of our
7956 * <code>test</code>-file (<code>testrun.test</code>). This will cause SCIP to solve our test instances
7957 * one after another and to create various output files (see \ref EVAL).
7958 *
7959 *
7960 * @section EVAL Evaluating a test run
7961 *
7962 * During computation, SCIP automatically creates the directory <code>scip/check/results/</code>
7963 * (if it does not already exist) and stores the following output files there.
7964 *
7965 * \arg <code>*.out</code> - output of <code>stdout</code>
7966 * \arg <code>*.err</code> - output of <code>stderr</code>
7967 * \arg <code>*.set</code> - copy of the used settings file
7968 *
7969 * \arg <code>*.res</code> - ASCII table containing a summary of the computational results
7970 * \arg <code>*.tex</code> - TeX table containing a summary of the computational results
7971 * \arg <code>*.pav</code> - <a href="http://www.gamsworld.org/performance/paver/">PAVER</a> output
7972 *
7973 * The last three files in the above list, i.e., the files containing a summary of the computational results,
7974 * can also be generated manually. Therefore the user has to call the <code>evalcheck.sh</code> script in the
7975 * @c check directory with the corresponding @c out file as argument. For example, this may be useful if the user stopped the
7976 * test before it was finished, in which case the last three files will not be automatically generated by SCIP.
7977 *
7978 * The last column of the ASCII summary table contains the solver status. We distinguish the following statuses: (in order of priority)
7979 *
7980 * \arg abort: solver broke before returning solution
7981 * \arg fail: solver cut off a known feasible solution (value of the <code>solu</code>-file is beyond the dual bound;
7982 * especially if problem is claimed to be solved but solution is not the optimal solution)
7983 * <b>or</b> if a final solution check revealed a violation of one of the original constraints.
7984 * \arg ok: solver solved problem with the value in solu-file
7985 * \arg solved: solver solved problem which has no (optimal) value in solu-file (since we here cannot detect the direction
7986 * of optimization, it is possible that a solver claims an optimal solution which contradicts a known feasible solution)
7987 * \arg better: solver found solution better than known best solution (or no solution was noted in the <code>solu</code>-file so far)
7988 * \arg gaplimit, sollimit: solver reached gaplimit or limit of number of solutions (at present: only in SCIP)
7989 * \arg timeout: solver reached any other limit (like time or nodes)
7990 * \arg unknown: otherwise
7991 *
7992 * Additionally the <code>evalcheck.sh</code> script can generate a <code>solu</code>-file by calling
7993 * \code
7994 * ./evalcheck.sh writesolufile=1 NEWSOLUFILE=<solu-file> <out-file>
7995 * \endcode
7996 * where <code><solu-file></code> denotes the filename of the new file where the solutions shall be
7997 * (and <code><out-file></code> denotes the output (<code>.out</code>) files to evaluate).
7998 *
7999 * Another feature can be enabled by calling:
8000 * \code
8001 * ./evalcheck.sh printsoltimes=1 ...
8002 * \endcode
8003 * The output has two additional columns containing the solving time until the first and the best solution was found.
8004 *
8005 *
8006 * @b Note: The @em basename of all these files is the same and has the following structure
8007 * which allows us to reconstruct the test run:
8008 *
8009 * \code
8010 * check.<test name>.<binary>.<machine name>.<setting name>
8011 * \endcode
8012 *
8013 * \arg <<code>test name</code>> indicates the name of the the test file, e.g., <code>testrun</code>
8014 * \arg <<code>binary</code>> defines the used binary, e.g., <code>scip-3.2.0.linux.x86_64.gnu.opt.spx</code>
8015 * \arg <<code>machine name</code>> tells the name of the machine, e.g., <code>mycomputer</code>
8016 * \arg <<code>setting name</code>> denotes the name of the used settings, e.g., <code>default</code>
8017 * means the (SCIP) default settings were used
8018 *
8019 * Using the examples out of the previous listing the six file names would have the name:
8020 *
8021 * \code
8022 * check.testrun.scip-1.1.0.linux.x86.gnu.opt.spx.mycomputer.default.<out,err,set,res,tex,pav>
8023 * \endcode
8024 *
8025 *
8026 * @section USING Using customized setting files
8027 *
8028 * It is possible to use customized settings files for the test run instead of testing SCIP with default settings.
8029 * These have to be placed in the directory <code>scip/settings/</code>.
8030 *
8031 * @b Note: Several common user parameters such as, e.g., the time limit and node limit parameters,
8032 * <b>cannot</b> be controlled by the settings file, whose specifications would be overwritten
8033 * by optional command line arguments to the <code>make test</code> command, see @ref ADVANCED
8034 * for a list of available advanced testing options that have to be specified from the command line.
8035 *
8036 * @b Note: Accessing settings files in subfolders of the @c settings directory is currently not supported.
8037 *
8038 * To run SCIP with a custom settings file, say for example <code>fast.set</code>, we call
8039 *
8040 * \code
8041 * make TEST=testrun SETTINGS=fast test
8042 * \endcode
8043 *
8044 * in the SCIP root directory. It is possible to enter a list of settings files as a double-quoted,
8045 * comma-separated list of settings names as <code>fast</code> above, i.e. <code>SETTINGS="fast,medium,slow"</code>
8046 * will invoke the solution process for every instance with the three settings <code>fast.set, medium.set, slow.set</code>
8047 * before continuing with the next instance from the <code>.test</code>-file. This may come in handy if the
8048 * whole test runs for a longer time and partial results are already available.
8049 *
8050 *
8051 * @section ADVANCED Advanced options
8052 *
8053 * We can further customize the test run by specifying the following options in the <code>make</code> call:
8054 *
8055 * \arg <code>CONTINUE</code> - continue the test run if it was previously aborted [default: "false"]
8056 * \arg <code>DISPFREQ</code> - display frequency of the output [default: 10000]
8057 * \arg <code>FEASTOL</code> - LP feasibility tolerance for constraints [default: "default"]
8058 * \arg <code>LOCK</code> - should the test run be locked to prevent other machines from performing the same test run [default: "false"]
8059 * \arg <code>MAXJOBS=n</code> - run tests on 'n' cores in parallel. Note that several instances are solved in parallel, but
8060 * only one thread is used per job (parallelization is not that easy) [default: 1]
8061 * \arg <code>MEM</code> - memory limit in MB [default: 6144]
8062 * \arg <code>NODES</code> - node limit [default: 2100000000]
8063 * \arg <code>TIME</code> - time limit for each test instance in seconds [default: 3600]
8064 * \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]
8065 * \arg <code>THREADS</code> - the number of threads used for solving LPs, if the linked LP solver supports multithreading [default: 1]
8066 * \arg <code>VALGRIND</code> - run valgrind on the SCIP binary; errors and memory leaks found by valgrind are reported as fails [default: "false"]
8067 *
8068 *
8069 * @section COMPARE Comparing test runs for different settings
8070 *
8071 * Often test runs are performed on the basis of different settings. In this case, it is useful to
8072 * have a performance comparison. For this purpose, we can use the <code>allcmpres.sh</code> script in
8073 * the @c check directory.
8074 *
8075 * Suppose, we performed our test run with two different settings, say <code>fast.set</code> and
8076 * <code>slow.set</code>. Assuming that all other parameters (including the SCIP binary), were the same,
8077 * we may have the following <code>res</code>-files in the directory <code>scip/check/results/</code>
8078 *
8079 * \code
8080 * check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.fast.res
8081 * check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.slow.res
8082 * \endcode
8083 *
8084 * For a comparison of both computations, we simply call
8085 *
8086 * \code
8087 * allcmpres.sh results/check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.fast.res \
8088 * results/check.testrun.scip-3.2.0.linux.x86_64.gnu.opt.spx.mycomputer.slow.res
8089 * \endcode
8090 *
8091 * in the @c check directory. This produces an ASCII table on the console that provide a detailed
8092 * performance comparison of both test runs. Note that the first <code>res</code>-file serves as reference
8093 * computation. The following list explains the output.
8094 * (The term "solver" can be considered as the combination of SCIP with a specific setting file.)
8095 *
8096 * \arg <code>Nodes</code> - Number of processed branch-and-bound nodes.
8097 * \arg <code>Time</code> - Computation time in seconds.
8098 * \arg <code>F</code> - If no feasible solution was found, then '#', empty otherwise.
8099 * \arg <code>NodQ</code> - Equals Nodes(i) / Nodes(0), where 'i' denotes the current solver and '0' stands for the reference solver.
8100 * \arg <code>TimQ</code> - Equals Time(i) / Time(0).
8101 * \arg <code>bounds check</code> - Status of the primal and dual bound check.
8102 *
8103 * \arg <code>proc</code> - Number of instances processed.
8104 * \arg <code>eval</code> - Number of instances evaluated (bounds check = "ok", i.e., solved to optimality
8105 * within the time and memory limit and result is correct). Only these instances are used in the calculation
8106 * of the mean values.
8107 * \arg <code>fail</code> - Number of instances with bounds check = "fail".
8108 * \arg <code>time</code> - Number of instances with timeout.
8109 * \arg <code>solv</code> - Number of instances correctly solved within the time limit.
8110 * \arg <code>wins</code> - Number of instances on which the solver won (i.e., the
8111 * solver was at most 10% slower than the fastest solver OR had the best
8112 * primal bound in case the instance was not solved by any solver within
8113 * the time limit).
8114 * \arg <code>bett</code> - Number of instances on which the solver was better than the
8115 * reference solver (i.e., more than 10% faster).
8116 * \arg <code>wors</code> - Number of instances on which the solver was worse than the
8117 * reference solver (i.e., more than 10% slower).
8118 * \arg <code>bobj</code> - Number of instances on which the solver had a better primal
8119 * bound than the reference solver (i.e., a difference larger than 10%).
8120 * \arg <code>wobj</code> - Number of instances on which the solver had a worse primal
8121 * bound than the reference solver (i.e., a difference larger than 10%).
8122 * \arg <code>feas</code> - Number of instances for which a feasible solution was found.
8123 * \arg <code>gnodes</code> - Geometric mean of the processed nodes over all evaluated instances.
8124 * \arg <code>shnodes</code> - Shifted geometric mean of the processed nodes over all evaluated instances.
8125 * \arg <code>gnodesQ</code> - Equals nodes(i) / nodes(0), where 'i' denotes the current
8126 * solver and '0' stands for the reference solver.
8127 * \arg <code>shnodesQ</code> - Equals shnodes(i) / shnodes(0).
8128 * \arg <code>gtime</code> - Geometric mean of the computation time over all evaluated instances.
8129 * \arg <code>shtime</code> - Shifted geometric mean of the computation time over all evaluated instances.
8130 * \arg <code>gtimeQ</code> - Equals time(i) / time(0).
8131 * \arg <code>shtimeQ</code> - Equals shtime(i) / shtime(0).
8132 * \arg <code>score</code> - N/A
8133 *
8134 * \arg <code>all</code> - All solvers.
8135 * \arg <code>optimal auto settings</code> - Theoretical result for a solver that performed 'best of all' for every instance.
8136 * \arg <code>diff</code> - Solvers with instances that differ from the reference solver in the number of
8137 * processed nodes or in the total number of simplex iterations.
8138 * \arg <code>equal</code> - Solvers with instances whose number of processed nodes and total number of
8139 * simplex iterations is equal to the reference solver (including a 10% tolerance) and where no timeout
8140 * occured.
8141 * \arg <code>all optimal</code> - Solvers with instances that could be solved to optimality by
8142 * <em>all</em> solvers; in particular, no timeout occurred.
8143 *
8144 * Since this large amount of information is not always needed, one can generate a narrower table by calling:
8145 * \code
8146 * allcmpres.sh short=1 ...
8147 * \endcode
8148 * where <code>NodQ</code>, <code>TimQ</code> and the additional comparison tables are omitted.
8149 *
8150 * If the <code>res</code>-files were generated with the parameter <code>printsoltimes=1</code>
8151 * we can enable the same feature here as well by calling:
8152 * \code
8153 * allcmpres.sh printsoltimes=1 ...
8154 * \endcode
8155 * As in the evaluation, the output contains the two additional columns of the solving time until the first and the best solution was found.
8156 *
8157 * @section STATISTICS Statistical tests
8158 *
8159 * The \c allcmpres script also performs two statistical tests for comparing different settings: For deciding whether
8160 * more feasible solutions have been found or more instances have been solved to optimality or not, we use a McNemar
8161 * test. For comparing the running time and number of nodes, we use a variant of the Wilcoxon signed rank test. A
8162 * detailed explanation can be found in the PhD thesis of Timo Berthold (Heuristic algorithms in global MINLP solvers).
8163 *
8164 * @subsection McNemar McNemar test
8165 *
8166 * Assume that we compare two settings \c S1 and \c S2 with respect to the number of instances solved to optimality
8167 * within the timelimit. The null hypothesis would be "Both settings lead to an equal number of instances being solved
8168 * to optimality", which we would like to disprove. Let \f$n_1\f$ be the number of instances solved by setting \c S1
8169 * 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
8170 * McNemar test statistic is
8171 * \f[
8172 * \chi^2 = \frac{(n_1 - n_2)^2}{n_1 + n_2}.
8173 * \f]
8174 * Under the null hypothesis, \f$\chi^2\f$ is chi-squared distributed with one degree of freedom. This allows to compute
8175 * a \f$p\f$-value as the probability for obtaining a similar or even more extreme result under the null hypothesis.
8176 * More explicitly, \c allcmpres uses the following evaluation:
8177 * - \f$0.05 < p\f$: The null hypothesis is accepted (marked by "X").
8178 * - \f$0.005 < p \leq 0.05\f$: The null hypothesis might be false (marked by "!").
8179 * - \f$0.0005 < p \leq 0.005\f$: The null hypothesis can be false (marked by "!!").
8180 * - \f$p \leq 0.0005\f$: The null hypothesis is very likely false (marked by "!!!").
8181 *
8182 * As an example consider the following output:
8183 * \code
8184 * McNemar (feas) x2 0.0000, 0.05 < p X
8185 * McNemar (opt) x2 6.0000, p ~ (0.005, 0.05] !
8186 * \endcode
8187 * Here, \c x2 represents \f$\chi^2\f$.
8188 *
8189 * In this case, the test with respect to the number of found feasible solutions is irrelevant, since their number is
8190 * equal. In particular, the null hypothesis gets accepted (i.e., there is no difference in the settings - this is
8191 * marked by "X").
8192 *
8193 * With respect to the number of instances solved to optimality within the timelimit, we have that \f$0.005 < p <=
8194 * 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
8195 * settings perform differently; this is marked by "!". In the concrete case, we have 230 instances, all of which are
8196 * solved by setting \c S2, but only 224 by setting \c S1.
8197 *
8198 * @subsection Wilcoxon Wilcoxon signed rank test
8199 *
8200 * Assume that we compare two settings \c S1 and \c S2 with respect to their solution times (within the time limit). We
8201 * generate a sorted list of the ratios of the run times, where ratios that are (absolutely or relatively) within 1\%
8202 * of 1.0 are discarded, and ratios between 0.0 and 0.99 are replaced with their negative inverse in order to
8203 * obtain a symmetric distribution for the ratios around the origin.
8204 * We then assign ranks 1 to \c N to the remaining \c N data points in nondecreasing
8205 * order of their absolute ratio. This yields two groups \c G1
8206 * 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
8207 * setting \c S1 is faster). Then the sums of the ranks in groups \c G1 and \c G2 are computed, yielding values \c R1
8208 * and \c R2, respectively.
8209 *
8210 * The Wilcoxon test statistic is then
8211 * \f[
8212 * z = \frac{\min(R1, R2) - \frac{N(N+1)}{4}}{\sqrt{\frac{N(N+1)(2N+1)}{24}}},
8213 * \f]
8214 * which we assume to be (approximately) normally distributed (with zero mean) and allows to compute the probability
8215 * \f$p\f$ that one setting is faster than the other. (Note that for \f$N \leq 60\f$, we apply a correction by
8216 * subtracting 0.5 from the numerator).
8217 *
8218 * As an example consider the following output:
8219 * \code
8220 * Wilcoxon (time) z -0.1285, 0.05 <= p X
8221 * Wilcoxon (nodes) z -11.9154, p < 0.0005 !!!
8222 * \endcode
8223 * While the \f$z\f$-value is close to zero for the run time, it is extremely negative regarding the solving nodes. This latter
8224 * 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
8225 * nodes than setting \c S2 is negligible (this null hypothesis is rejected - marked by "!!!").
8226 *
8227 * However, the null hypothesis is not rejected with respect to the run time. In the concrete case, setting \c S1 has a
8228 * 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
8229 * 0.88. Still - the null hypothesis is not rejected.
8230 *
8231 * @section SOLVER Testing and Evaluating using GAMS
8232 *
8233 * Analogously to the target <code>test</code> there is another target to run automated tests with <a href="http://www.gams.com/">gams</a>
8234 * \code
8235 * make testgams GAMSSOLVER=xyz
8236 * \endcode
8237 * For this target, the option GAMSSOLVER has to be given to specify the name of a GAMS solver to run, e.g. GAMSSOLVER=SCIP.
8238 * Additional advanced options specific to this target are:
8239 * GAMS to specify the GAMS executable (default: gams),
8240 * GAP to specify a gap limit (default: 0.0),
8241 * CLIENTTMPDIR to specify a directory where GAMS should put its scratch files (default: /tmp),
8242 * 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).
8243 * The following options are NOT supported (and ignored): DISPFREQ, FEASTOL, LOCK.
8244 * 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).
8245 *
8246 * Note: This works only if the referred programs are installed globally on your machine.
8247 *
8248 * The above options like <code>TIME</code> are also available for gams.
8249 *
8250 * After the testrun there should be an <code>.out</code>, an <code>.err</code> and a <code>.res</code> file
8251 * with the same basename as described above.
8252 *
8253 * Furthermore you can also use the script <code>allcmpres.sh</code> for comparing results.
8254 *
8255 * @section PYTHON Testing using PySCIPOpt
8256 *
8257 * To run a python script that uses PySCIPOpt with <code>make test</code> or <code>make testcluster</code>, one has to
8258 * specify the python code to execute with the option <code>EXECUTABLE=/full/path/to/python-script.py</code>.
8259 * Note that <code>python-script.py</code> must be an executable file.
8260 * In addition, one <b>must</b> specify which python it should run with the option <code>PYTHON=my-python</code>.
8261 * The reason for this is that one usually installs PySCIPOpt in a virtual environment, thus only the python of the
8262 * virtual environment will work with the python script.
8263 *
8264 * The scripts work in such a way that they pass information to SCIP like the setting files, the instance name, and some other options.
8265 * It is the responsability of the python script <code>python-script.py</code> to parse this information.
8266 * Thus, you need to modify your python script to read the setting files and the other options provided by the testing scripts.
8267 * An example of how to do this is provided in <code>scip/check/scip-runner.py</code>.
8268 * One should either modify <code>scip/check/scip-runner.py</code> or include the <code>build_model()</code> function
8269 * into your script to correctly read the options passed by the scripts.
8270 *
8271 * An example of how to run the tests is
8272 * \code
8273 * make test EXECUTABLE=/full/path/to/scip/check/scip-runner.py PYTHON=python
8274 * \endcode
8275 */
8276
8277/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
8278
8279/**@page COUNTER How to use SCIP to count/enumerate feasible solutions
8280 *
8281 * SCIP is capable of computing (count or enumerate) the number of feasible solutions of a given constraint integer
8282 * program. In case continuous variables are present, the number of feasible solutions for the projection to the
8283 * integral variables is counted/enumerated. This means, an assignment to the integer variables is counted if the
8284 * remaining problem (this is the one after fixing the integer variables w.r.t. to this assignment) is feasible.
8285 *
8286 * As a first step you have to load or create your problem in the usual way. In case of using the
8287 * interactive shell, you use the <code>read</code> command:
8288 *
8289 * <code>SCIP&gt; read &lt;file name&gt;</code>
8290 *
8291 * Afterwards you can count the number of feasible solution with the command <code>count</code>.
8292 *
8293 * <code>SCIP&gt; count</code>
8294 *
8295 * @note After completing the counting process, SCIP will terminate with status <tt>infeasible</tt>. This is intended
8296 * behavior, because SCIP counts solutions by the following internal mechanism. Each feasible solution that is found is
8297 * reported as infeasible to the SCIP core. This avoids that SCIP performs reductions based on the primal bound that
8298 * could cut off suboptimal feasible solutions, which would then be missing in the count. However, as a result, the
8299 * SCIP core has not found any feasible solutions during the search and reports status <tt>infeasible</tt>.
8300 *
8301 * By default, SCIP only counts the number of solutions but does not store (enumerate) them. If you are interested in
8302 * that see \ref COLLECTALLFEASEBLES.
8303 *
8304 * @note Since SCIP version 2.0.0 you do not have to worry about the impact of dual reductions anymore. These are
8305 * automatically turned off. The only thing you should switch off are restarts. These restarts can lead to a wrong
8306 * counting process. We recommend using the counting settings which can be set in the interactive shell as follows:
8307 *
8308 * <code>SCIP&gt; set emphasis counter</code>
8309 *
8310 * The SCIP callable library provides an interface method SCIPcount() which allows users to count the number of feasible
8311 * solutions to their problem. The method SCIPsetParamsCountsols(), which is also located in cons_countsols.h, loads the
8312 * predefined counting settings to ensure a safe count. The complete list of all methods that can be used for counting
8313 * via the callable library can be found in cons_countsols.h.
8314 *
8315 *
8316 * @section COUNTLIMIT Limit the number of solutions which should be counted
8317 *
8318 * It is possible to give a (soft) upper bound on the number solutions that should be counted. If this upper bound is
8319 * exceeded, SCIP will be stopped. The name of this parameter is <code>constraints/countsols/sollimit</code>. In
8320 * the interactive shell this parameter can be set as follows:
8321 *
8322 * <code>SCIP&gt; set constraints countsols sollimit 1000</code>
8323 *
8324 * In case you are using the callable library, this upper bound can be assigned by calling SCIPsetLongintParam() as follows:
8325 *
8326 * \code
8327 * SCIP_CALL( SCIPsetLongintParam( scip, "constraints/countsols/sollimit", 1000) );
8328 * \endcode
8329 *
8330 *
8331 * The reason why this upper bound is soft comes from the fact that, by default, SCIP uses a technique called unrestricted
8332 * subtree detection. Using this technique it is possible to detect several solutions at once. Therefore, it can happen
8333 * that the solution limit is exceeded before SCIP is stopped.
8334 *
8335 * @section COLLECTALLFEASEBLES Collect all feasible solutions
8336 *
8337 * Per default SCIP only counts all feasible solutions. This means, these solutions are not stored. If you switch the
8338 * parameter <code>constraints/countsols/collect</code> to TRUE (the default value is FALSE) the detected solutions are
8339 * stored. Changing this parameter can be done in the interactive shell
8340 *
8341 * <code>SCIP&gt; set constraints countsols collect TRUE</code>
8342 *
8343 * as well as via the callable library
8344 *
8345 * \code
8346 * SCIP_CALL( SCIPsetBoolParam( scip, "constraints/countsols/collect", TRUE) );
8347 * \endcode
8348 *
8349 * @note The solution which are collected are stored w.r.t. the active variables. These are the variables which got not
8350 * removed during presolving.
8351 *
8352 * In case you are using the interactive shell you can write all collected solutions to a file as follows
8353 *
8354 * <code>SCIP&gt; write allsolutions &lt;file name&gt;</code>
8355 *
8356 * In that case the sparse solutions are unrolled and lifted back into the original variable space.
8357 *
8358 * The callable library provides a method which gives access to all collected sparse solutions. That is,
8359 * SCIPgetCountedSparseSolutions(). The sparse solutions you get are defined w.r.t. active variables. To get solutions
8360 * w.r.t. to the original variables. You have to do two things:
8361 *
8362 * -# unroll each sparse solution
8363 * -# lift each solution into original variable space by extending the solution by those variable which got removed
8364 * during presolving
8365 *
8366 * The get the variables which got removed during presolving, you can use the methods SCIPgetFixedVars() and
8367 * SCIPgetNFixedVars(). The method SCIPgetProbvarLinearSum() transforms given variables, scalars and constant to the
8368 * corresponding active variables, scalars and constant. Using this method for a single variable gives a representation
8369 * for that variable w.r.t. the active variables which can be used to compute the value for the considered solution (which
8370 * is defined w.r.t. active variables).
8371 *
8372 * For that complete procedure you can also check the source code of
8373 * \ref SCIP_DECL_DIALOGEXEC(SCIPdialogExecWriteAllsolutions) "SCIPdialogExecWriteAllsolutions()" cons_countsols.c which
8374 * does exactly that.
8375 *
8376 *
8377 * @section COUNTOPTIMAL Count number of optimal solutions
8378 *
8379 * If you are interested in counting the number of optimal solutions, this can be done with SCIP using the
8380 * <code>count</code> command by applying the following steps:
8381 *
8382 * -# Solve the original problem to optimality and let \f$c^*\f$ be the optimal value
8383 * -# Added the objective function as constraint with left and right hand side equal to \f$c^*\f$
8384 * -# load the adjusted problem into SCIP
8385 * -# use the predefined counting settings
8386 * -# start counting the number of feasible solutions
8387 *
8388 * If you do this, SCIP will collect all optimal solutions of the original problem.
8389 *
8390 */
8391
8392/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
8393
8394/** @page SYMMETRY How to use symmetry handling in SCIP
8395 *
8396 * Symmetry handling is an important feature of SCIP that allows to discard symmetric subproblems from the
8397 * branch-and-bound tree, and thus, can substantially reduce the running time. To handle symmetries, SCIP
8398 * automatically detects symmetries and then applies (combinations of) symmetry handling methods.
8399 *
8400 * @section SYMDETECT Symmetry detection
8401 *
8402 * SCIP can detect two types of symmetries: permutation symmetries and signed permutation symmetries.
8403 * In a purely integer linear setting
8404 * \f[
8405 * \max \{ c^{\top} x : Ax \leq b,\; x \in \mathbb{Z}^n \},
8406 * \f]
8407 * a permutation symmetry is a permutation \f$\gamma\f$ of \f$\{1,\dots,n\}\f$ that acts on vector \f$x\f$ by
8408 * permuting its coordinates via \f$\gamma(x) = (x_{\gamma^{-1}(1)}, \dots, x_{\gamma^{-1}(n)})\f$
8409 * such that
8410 *
8411 * -# \f$\gamma\f$ leaves the objective invariant, i.e., \f$c^{\top}x = c^{\top}\gamma(x)\f$, and
8412 * -# \f$\gamma\f$ maps feasible solutions onto feasible solutions, i.e., \f$Ax \leq b\f$ if and only
8413 * if \f$A\gamma(x) \leq b\f$.
8414 *
8415 * Signed permutation symmetries are defined similarly and allow to also handle symmetries arising from
8416 * reflections of the feasible region along standard hyperplanes, e.g., mapping \f$x_i\f$ to \f$-x_i\f$
8417 * and keeping the remaining entries of a solution vector \f$x\f$ invariant. Formally, a signed permutation \f$\gamma\f$
8418 * is a permutation of the set \f$\{\pm 1, \dots, \pm n\}\f$ such that \f$\gamma(-i) = - \gamma(i)\f$
8419 * for all \f$i \in \{1,\dots,n\}\f$. A signed permutation acts on a vector \f$x\f$ as
8420 * \f$\gamma(x) = (\mathrm{sgn}(\gamma^{-1}(1))x_{|\gamma^{-1}(1)|},\dots,
8421 * \mathrm{sgn}(\gamma^{-1}(n))x_{|\gamma^{-1}(n)|})\f$,
8422 * where \f$\mathrm{sgn}(\cdot)\f$ is the sign function. The remaining properties of a symmetry are the same.
8423 * It is possible to switch between these two types of symmetries via the
8424 * parameter <code>propagating/symmetry/symtype</code>.
8425 * Moreover, to detect more general signed permutations, one can shift variables with a
8426 * bounded domain to be centered at the origin. This way, also variables with, e.g., domains \f$[1,2]\f$
8427 * and \f$[0,1]\f$ can be symmetric. In SCIP, we implement this shift only within symmetry detection
8428 * to find generalized signed permutations; the variable bounds of the problem itself remain unchanged.
8429 *
8430 * Since both definitions depend on the feasible region of the integer program, which is unknown
8431 * in general, SCIP only computes symmetries that leave the formulation of the optimization problem
8432 * invariant. To detect such formulation symmetries, SCIP builds an auxiliary colored graph whose
8433 * color-preserving automorphisms correspond to symmetries of the integer program. The symmetries of
8434 * the graph, and thus of the integer program, are then computed by an external graph automorphism
8435 * library that needs to be linked to SCIP. Currently, SCIP can use two such libraries: The graph
8436 * automorphism libraries bliss or nauty/traces are the basic workhorses to detect symmetries. Moreover, one can use
8437 * sassy, a graph symmetry preprocessor which passes the preprocessed graphs to bliss or nauty/traces.
8438 * The current default is to use nauty in combination with sassy for symmetry detection.
8439 * To use other symmetry packages, options <code>SYM</code> and <code>-DSYM</code> in the Makefile and CMake
8440 * system, respectively, need to be set.
8441 *
8442 * Besides purely integer linear problems, SCIP also supports symmetry detection for general
8443 * constraint mixed-integer programs containing most of the constraint types that can be handled
8444 * by SCIP. In particular, symmetries of mixed-integer nonlinear problems can be detected.
8445 * Moreover, symmetries can also be detected in code containing customized constraints.
8446 * To this end, a suitable callback needs to be implemented, see \ref SYMDETECTCUSTOM.
8447 *
8448 * @subsection SYMPROCESS Processing symmetry information
8449 *
8450 * After symmetries have been computed, SCIP has access to a list \f$\gamma_1,\dots,\gamma_m\f$ of
8451 * (signed) permutations that generate a group \f$\Gamma\f$ of symmetries of the optimization problem. That
8452 * is, SCIP has not access to all permutations in \f$\Gamma\f$, but only a set of generators. Based
8453 * on these generators, SCIP analyzes the group \f$\Gamma\f$ and checks whether it can be split into
8454 * independent factors. That is, whether there exist subgroups \f$\Gamma_1,\dots,\Gamma_k\f$ of
8455 * \f$\Gamma\f$ that act on pairwise independent sets of variables such that \f$\bigcup_{i=1}^k \Gamma_i = \Gamma\f$.
8456 * In this case, SCIP can handle the symmetries of the different subgroups independently. In particular,
8457 * different subgroups can be treated by different symmetry handling methods.
8458 *
8459 * @section SYMMETHODS Symmetry handling methods
8460 *
8461 * Most symmetry handling methods available in SCIP have only been implemented for ordinary permutation symmetries,
8462 * and not for signed permutation symmetries. In the following, we silently assume that the described methods
8463 * deal with ordinary permutation symmetries if not mentioned differently.
8464 * To handle symmetries, SCIP uses three different classes of methods, which we detail below.
8465 *
8466 * @subsection SYMCONSS Static symmetry handling constraints for binary variable domains
8467 *
8468 * SCIP contains three constraint handlers for handling symmetries of binary variables: the symresack,
8469 * orbisack, and orbitope constraint handler. Given a symmetry \f$\gamma\f$,
8470 * the symresack constraint handler enforces that a solution vector \f$x\f$ is not lexicographically
8471 * smaller than its image \f$\gamma(x)\f$. This constraint is enforced by a propagation algorithm
8472 * and separating inequalities. Moreover, given the disjoint cycle decomposition of \f$\gamma\f$,
8473 * SCIP checks, for each cycle of \f$\gamma\f$, whether all variables in the cycle are contained
8474 * in set packing or partitioning constraints. If this is the case, specialized inequalities can
8475 * be separated.
8476 *
8477 * In case the permutation \f$\gamma\f$ is an involution, i.e., \f$\gamma(\gamma(x)) = x\f$,
8478 * specialized separation and propagation algorithms can be used, which are implemented in the
8479 * orbisack constraint handler. For orbisack constraints, also facet-defining inequalities of the
8480 * convex hull of all binary points \f$x\f$ being not lexicographically smaller than \f$\gamma(x)\f$
8481 * can be separated. Since the coefficients in these inequalities grow exponentially large which might
8482 * cause numerical instabilities, the separation of these inequalities is disabled by default, but can be
8483 * enabled via the parameter <code>constraints/orbisack/orbiSeparation</code>. Furthermore, to avoid
8484 * numerical instabilities, the parameter <code>constraints/orbisack/coeffbound</code> controls the
8485 * maximum absolute value of a coefficient in separated facet-defining inequalities.
8486 *
8487 * Finally, the orbitope constraint handler is able to handle symmetries of special symmetric groups \f$\Gamma\f$.
8488 * For orbitopes to be applicable, the affected variables need to be arranged in a matrix \f$X\f$ such that
8489 * the symmetries in \f$\Gamma\f$ permute the columns of \f$X\f$. Symmetries are then handled by orbitope
8490 * constraints by enforcing to only compute solution matrices \f$X\f$ whose columns are sorted lexicographically
8491 * non-increasingly. To this end, a propagation algorithm is used and inequalities are separated. In case
8492 * the variables of each row of the matrix \f$X\f$ are contained in a set packing or partitioning constraint,
8493 * specialized propagation and separation routines are used.
8494 *
8495 * @subsection SYMPROP Dynamic symmetry handling by propagation
8496 *
8497 * Static symmetry handling enforces a lexicographic ordering on the variable solution vectors.
8498 * The pro of that approach, is that throughout the solving process, the same lexicographic ordering constraint
8499 * is used. This means that already during presolving certain symmetry reductions can be made.
8500 * The con of this approach is that an ordering of the variables for lexicographic comparisons have to be made
8501 * before solving. Consequently, if reductions of certain variable domains are found, but these variables are compared
8502 * late by the lexicographic comparison order, the effect for symmetry handling is very slim.
8503 *
8504 * Dynamic symmetry handling addresses this issue by propagating symmetry handling constraints, where the variable
8505 * comparison ordering are determined while solving, attempting to make strong symmetry handling reductions early on.
8506 * Dynamic symmetry handling removes feasible solutions of the problem, while it is guaranteed that at least one
8507 * symmetric solution remains feasible.
8508 *
8509 * Whether dynamic or static symmetry handling methods are used, is determined by the boolean parameter
8510 * <code>propagating/symmetry/usedynamicprop</code>.
8511 * SCIP features three dynamic symmetry handling methods.
8512 * SCIP only provides propagation methods for handling these symmetries,
8513 * and the methods work on variables with arbitrary (so also non-binary) variable domains.
8514 *
8515 * -# Orbitopal reduction is the dynamic counterpart of orbitopal fixing. This method can be used if the variables
8516 * can be arranged without duplicates in a matrix, and symmetries permute the columns of this matrix. This method
8517 * propagates the variable domains such that solutions in matrix-form have lexicographically decreasing columns,
8518 * with respect to the dynamically chosen row and column order.
8519 * Orbitopal reduction respects the parameter <code>propagating/symmetry/detectorbitopes</code>.
8520 * -# Lexicographic reduction is the dynamic counterpart of symresack and orbisack propagation.
8521 * Lexicographic reduction respects the parameter <code>propagating/symmetry/addsymresacks</code>.
8522 * At the moment, the implementation of this method is the only one that allows to also handle signed permutation
8523 * symmetries.
8524 * -# Orbital reduction is a generalization of orbital fixing that also works for non-binary variable domains.
8525 * Orbital reduction respects the 2-bit of the bitset <code>misc/usesymmetry</code>.
8526 * See \ref SYMMETHODSELECT "method selection". Since there is no static counterpart, this method ignores
8527 * <code>propagating/symmetry/usedynamicprop</code>.
8528 *
8529 * In all cases, the dynamic variable ordering is derived from the branching decisions.
8530 * In particular, at different branch-and-bound tree nodes, a different variable ordering can be active.
8531 * Since the symmetries are handled for independent factors of the symmetry group, a different variable ordering method
8532 * can be used for handling symmetries in different factors. In SCIP, the same method is used for orbital reduction and
8533 * for lexicographic reduction, which means that these two methods are compatible and can be used simultaneously in the
8534 * same factor. Orbitopal reduction uses a different method.
8535 *
8536 * As SCIP might restart the branch-and-bound process, which removes information regarding the branching decisions,
8537 * we need to make sure that correct reductions are found after a restart.
8538 * If a restart occurs, static symmetry handling methods are preserved. Since dynamic symmetry handling methods
8539 * depend on the branch-and-bound tree structure, and because the prior branch-and-bound tree is removed,
8540 * the dynamic symmetry handling methods are disabled after a restart.
8541 *
8542 * @subsection SYMSST SST cuts
8543 *
8544 * The Schreier-Sims table (SST) is a table that contains certain information about symmetry groups
8545 * and can be used, among others, to derive symmetry handling inequalities. The corresponding SST cuts
8546 * are symmetry handling inequalities that are defined iteratively in rounds \f$r = 1,\dots,R\f$.
8547 * In each round \f$r\f$, a leader variable \f$\ell_r\f$ is selected and the group
8548 * \f$\Gamma_r = \{ \gamma \in \Gamma : \gamma(\ell_i) = \ell_i \text{ for all } i = 1,\dots,r-1\}\f$
8549 * is considered. Then, the symmetry handling inequalities of round \f$r\f$ are defined as
8550 * \f$x_{\ell_r} \geq x_j\f$ for all \f$j \in \{\gamma(i) : i \in \{1,\dots,n\}\}\f$.
8551 * The latter set is called the orbit of leader \f$\ell_r\f$.
8552 *
8553 * SST cuts admit many degrees of freedom. In particular, they are not limited to binary variables
8554 * but can be used for arbitrary variable types. A user can gain control over the selection process of
8555 * SST cuts via several parameters. For instance,
8556 *
8557 * - <code>sstleadervartype</code> is a bitset encoding the variable types of leaders: the 1-bit models binary,
8558 * the 2-bit integer, the 4-bit implicit integer, and the 8-bit continuous variables. That is, a value
8559 * of 9 models that the leader can be a binary or continuous variable.
8560 * - <code>sstleaderrule</code> ranges from 0 to 2 and models whether a leader is the first variable in
8561 * its orbit, the last variable in its orbit, or a variable with most conflicts with other variables in
8562 * the orbit, respectively.
8563 * - <code>ssttiebreakrule</code> ranges from 0 to 2 and models whether an orbit of minimum size, maximum
8564 * size or with most variables being in conflict to the leader is selected, respectively.
8565 * - <code>sstmixedcomponents</code> whether SST cuts are also applied if a symmetries do not only affect
8566 * variables of a single type.
8567 * - <code>sstaddcuts</code> whether SST cuts are added to the problem. If no cuts are added, only
8568 * binary variables might be fixed to 0 if they are in conflict with the leader.
8569 *
8570 * @subsection SYMMETHODSELECT Selecting symmetry handling methods
8571 *
8572 * The symmetry handling methods explained above can be enabled and disabled via the parameter
8573 * <code>misc/usesymmetry</code>, which encodes the enabled methods via a bitset that ranges between 0
8574 * and 7: the 1-bit encodes symmetry handling constraints, the 2-bit encodes orbital reduction, and the
8575 * 4-bit encodes SST cuts. For example, <code>misc/usesymmetry = 3</code> enables symmetry handling
8576 * constraints and orbital reduction, whereas <code>misc/usesymmetry = 0</code> disables symmetry handling.
8577 * In the following, we explain how the combination of different symmetry handling methods works.
8578 *
8579 * The default strategy of SCIP is to handle symmetries via the bitset value 7, i.e., symmetry handling
8580 * constraints, orbital reduction, and SST cuts are enabled. To make sure that the different methods are
8581 * compatible, the following steps are carried out:
8582 *
8583 * -# SCIP determines independent subgroups \f$\Gamma_1,\dots,\Gamma_k\f$ as described in \ref SYMPROCESS.
8584 * Then, for each subgroup \f$\Gamma_i\f$, different symmetry handling methods can be applied.
8585 * -# For each subgroup \f$\Gamma_i\f$, a heuristic is called that checks whether orbitopes are applicable
8586 * to handle the entire subgroup. If yes, this subgroup is handled by orbitopes and no other
8587 * symmetry handling methods.
8588 * -# Otherwise, if parameter <code>propagating/symmetry/detectsubgroups</code> is <code>TRUE</code>
8589 * and <code>propagating/symmetry/usedynamicprop</code> is <code>FALSE</code>, a
8590 * heuristic is called to detect whether "hidden" orbitopes are present. That is, whether some but not
8591 * all symmetries of \f$\Gamma_i\f$ can be handled by orbitopes. If sufficiently many symmetries can
8592 * be handled by orbitopes, orbitopes are applied and, if parameter <code>propagating/symmetry/addweaksbcs</code>
8593 * is TRUE, some compatible SST cuts are added, too. Besides this, no further symmetry handling methods
8594 * are applied for \f$\Gamma_i\f$.
8595 * -# Otherwise, orbital reduction is used. If <code>propagating/symmetry/usedynamicprop</code> and
8596 * <code>propagating/symmetry/addsymresacks</code> are <code>TRUE</code>, then also the dynamic lexicographic
8597 * reduction method is used.
8598 * -# Otherwise, if the majority of variables affected by \f$\Gamma_i\f$ are non-binary, SST cuts are applied
8599 * to handle \f$\Gamma_i\f$. No further symmetry handling methods are applied for \f$\Gamma_i\f$.
8600 *
8601 * @note If orbital reduction is enabled, a factor \f$\Gamma_i\f$ can always be handled by this method.
8602 * As such, by default, no SST cuts will be added.
8603 *
8604 * @note Depending on the setting of <code>misc/usesymmetry</code>, it might be possible that a symmetry component is
8605 * not handled. For instance, if only orbitopal reduction is used
8606 * (i.e., <code>propagating/symmetry/detectorbitopes</code> is set to 1),
8607 * and if a symmetry component is no orbitope, no symmetry is handled for that component at all.
8608 *
8609 *
8610 * @subsection SYMTIMING Controlling the timing of symmetry computation
8611 *
8612 * Since presolving might both remove and introduce formulation symmetries, the timing of computing symmetries
8613 * can be changed via the parameter <code>propagating/symmetry/symtiming</code>.
8614 * The parameter takes value 0, 1, or 2, corresponding to computing symmetries before presolving,
8615 * during presolving, or at the end of presolving, respectively.
8616 * Based on the computed symmetries, SCIP enables some symmetry handling methods as explained above.
8617 *
8618 * @subsection SYMDETECTCUSTOM Symmetry detection for customized constraints
8619 *
8620 * To detect (signed) permutation symmetries, SCIP requests from each constraint present in the problem to be solved
8621 * a node and edge colored graph whose symmetries correspond to the symmetries of the corresponding constraint.
8622 * This information is provided by two callbacks, the SCIP_DECL_CONSGETPERMSYMGRAPH callback for permutation
8623 * symmetries and the SCIP_DECL_CONSGETSIGNEDPERMSYMGRAPH callback for signed permutation symmetries. If a
8624 * constraint handler does not implement one of these callbacks, SCIP will not detect symmetries of the corresponding
8625 * type.
8626 *
8627 * In the following, we briefly describe how such a symmetry detection graph looks like for linear constraints.
8628 * Afterwards, we mention the basic setup of the symmetry detection graphs and how the callbacks could be implemented
8629 * for customized constraints.
8630 *
8631 * @subsubsection SYMDETECTLINEAR Symmetry detection graphs for linear constraints
8632 *
8633 * Simple permutation symmetries of a linear constraint \f$\sum_{i = 1}^n a_ix_i \leq \beta\f$ are given
8634 * by permutations that exchange equivalent variables with the same coefficients. These symmetries can be encoded
8635 * by a graph with the following structure. For every variable \f$x_i\f$, the graph contains a node \f$v_i\f$
8636 * that receives a color that uniquely determines the type of the variable (lower/upper bound, objective coefficient,
8637 * integrality). Moreover, the graph contains a node \f$w\f$ that receives a color corresponding to the right-hand side
8638 * \f$\beta\f$. Node \f$w\f$ is then connected with all nodes corresponding to variables. Edge \f$\{w,v_i\}\f$ then
8639 * receives a color corresponding to the coefficient \f$a_i\f$. Then, every automorphism of this graph corresponds to a
8640 * permutation symmetry of the linear constraint.
8641 *
8642 * For signed permutation symmetries, almost the same construction can be used. The only difference is that also
8643 * nodes \f$v_{-i}\f$ need to be introduced that correspond to the negation of variable \f$x_i\f$. These negated
8644 * variable nodes are then also connected with node \f$\beta\f$ and the corresponding edge receives color \f$-a_i\f$.
8645 * Finally, to make sure that the corresponding symmetry corresponds to a signed permutation \f$\gamma\f$, i.e.,
8646 * \f$\gamma(-i) = - \gamma(i)\f$, one also needs to add the edges \f$\{v_i,v_{-i}\}\f$ that remain uncolored.
8647 * Note that the color of node \f$v_{-i}\f$ also needs to uniquely determine the negated variable bounds and
8648 * objective coefficient.
8649 *
8650 * @subsubsection SYMDETECTRULES Principles for building symmetry detection graphs
8651 *
8652 * A symmetry detection graph of a constraint needs to have the property that each of its automorphisms corresponds
8653 * to a (signed) permutation of the constraint. Moreover, the corresponding constraint handler of the constraints
8654 * needs to be encoded in the graph to make sure that only symmetries between equivalent constraints can be computed.
8655 * Among others, this can be achieved by assigning the nodes and edges appropriate colors. To make sure that the
8656 * colors are compatible between the different symmetry detection graphs, SCIP automatically determines the colors of
8657 * nodes and edges based on information that is provided by the user (or the creator of the graph).
8658 *
8659 * A pointer to a globally maintained symmetry detection graph is provided to the callbacks. The nodes and edges of the
8660 * graph of a constraint are added to this global graph.
8661 * The nodes of the graph need to be added via the functions <code>SCIPaddSymgraphValnode()</code>
8662 * and <code>SCIPaddSymgraphConsnode()</code>. The first function can be used to create nodes corresponding to
8663 * a numerical value like \f$\beta\f$ in the above example, the latter function creates a node corresponding to
8664 * a provided constraint. This ensures that only symmetry detection graphs from the same constraint handler
8665 * can be isomorphic. The colors of the nodes are then computed automatically by SCIP based on the information
8666 * that is provided the functions creating these nodes. This ensures that node colors are compatible.
8667 *
8668 * Edges are created via the function <code>SCIPaddSymgraphEdge()</code> which receives, among others, the
8669 * indices of created nodes. Note that there is no function for creating variable nodes as SCIP automatically
8670 * creates nodes for variables. Their indices can be accessed via <code>SCIPgetSymgraphVarnodeidx()</code> for
8671 * original variables and <code>SCIPgetSymgraphNegatedVarnodeidx()</code> for negated variables used for
8672 * signed permutations. The edges between variables \f$x_i\f$ and \f$-x_i\f$ are also automatically present
8673 * in the symmetry detection graph for signed permutation symmetries. The function <code>SCIPaddSymgraphEdge()</code>
8674 * also takes a numerical value as argument, which allows to assign an edge a weight (e.g., \f$a_i\f$
8675 * as in the above example).
8676 *
8677 * Moreover, special nodes, so-called operator nodes, can be added via <code>SCIPaddSymgraphOpnode()</code>.
8678 * Such nodes allow to model special structures of a constraint, which allow to have more degrees of freedom in
8679 * creating symmetry detection graphs. Different operators are distinguished by an integral value.
8680 * Their encoding is thus similar to the one of nodes created by <code>SCIPaddSymgraphValnode()</code>.
8681 * In computing colors, operator nodes are treated differently though, which allows to distinguish
8682 * operator 2 from the numerical value 2.
8683 *
8684 * @subsubsection SYMDETECTEXAMPLES Example for creating symmetry detection callbacks
8685 *
8686 * Let \f$G = (V,E)\f$ be an undirected graph with node weights \f$c_v\f$, \f$v \in C\f$. The maximum weight
8687 * stable set problem can be modeled via the integer program
8688 * \f\[ \max\Big\{ \sum_{v \in V} c_vx_v : x_u + x_v \leq 1 \text{ for all } \{u,v\} \in E,\; x \in \{0,1\}^V\Big\}.\f\]
8689 * Suppose a user wants to implement a constraint handler <code>cons_stableset</code> that enforces a solution to define
8690 * a stable set in \f$G\f$, e.g., by propagation methods and separating edge and clique inequalities.
8691 * Then, the symmetries of the constraint are the weight-preserving automorphisms of the underlying graph \f$G\f$.
8692 * The symmetry detection graph thus can be almost a copy of \f$G\f$.
8693 *
8694 * In our construction, we introduce for each node \f$v\f$ of the graph an operator node \f$v'\f$.
8695 * Moreover, for each edge \f$\{u,v\}\in E\f$, we add the edges \f$\{u',v'\}\f$ to the symmetry detection graph.
8696 * To identify the symmetry detection graph as derived from <code>cons_stableset</code>, we add a constraint node
8697 * that is connected with all operator nodes, which preserves the automorphisms of \f$G\f$. Finally, each
8698 * node \f$v'\f$ is connected with the corresponding variable node for \f$x_v\f$ by an edge.
8699 *
8700 * In the following, we present a code snippet showing how to implement the above mentioned symmetry detection graph.
8701 * We assume that the constraint data <code>consdata</code> contains the following fields
8702 *
8703 * - <code>nnodes</code> number of nodes in graph;
8704 * - <code>nedges</code> number of edges in graph;
8705 * - <code>first</code> array containing the first nodes of each edge;
8706 * - <code>second</code> array containing the second nodes of each edge;
8707 * - <code>weights</code> array containing for each node its corresponding weight;
8708 * - <code>vars</code> array containing a binary variable for each node modeling whether node is present in stable set.
8709 *
8710 * The code for creating the symmetry detection callback could then look like this.
8711 *
8712 * \code{.c}
8713 * #define NODEOP 1
8714 * static
8715 * SCIP_DECL_CONSGETPERMSYMGRAPH(consGetPermsymGraphStableSet)
8716 * {
8717 * SCIP_CONSDATA* consdata;
8718 * int* idx;
8719 * int vidx;
8720 * int nnodes;
8721 * int v;
8722 *
8723 * consdata = SCIPconsGetData(cons);
8724 * nnodes = consdata->nnodes;
8725 *
8726 * SCIP_CALL( SCIPallocBufferArray(scip, &idx, nnodes + 1) );
8727 *
8728 * // create operator nodes and constraint node
8729 * for( v = 0; v < nnodes; ++v )
8730 * {
8731 * SCIP_CALL( SCIPaddSymgraphOpnode(scip, graph, NODEOP, &idx[v]) );
8732 * }
8733 * SCIP_CALL( SCIPaddSymgraphConsnode(scip, graph, cons, 0.0, 0.0, &idx[nnodes]) );
8734 *
8735 * // add edges of underlying graph
8736 * for( v = 0; v < consdata->nedges; ++v )
8737 * {
8738 * SCIP_CALL( SCIPaddSymgraphEdge(scip, graph, idx[consdata->first[v]], idx[consdata->second[v]], FALSE, 0.0) );
8739 * }
8740 *
8741 * // connect nodes with constraint node
8742 * for( v = 0; v < nnodes; ++v )
8743 * {
8744 * SCIP_CALL( SCIPaddSymgraphEdge(scip, graph, idx[v], nodeidx[nnodes], FALSE, 0.0) );
8745 * }
8746 *
8747 * // connect operator nodes with variable nodes, assign edges weight of node
8748 * for( v = 0; v < nnodes; ++v )
8749 * {
8750 * vidx = SCIPgetSymgraphVarnodeidx(scip, graph, consdata->vars[v]);
8751 * SCIP_CALL( SCIPaddSymgraphEdge(scip, graph, idx[v], vidx, TRUE, consdata->weights[v]) );
8752 * }
8753 *
8754 * SCIPfreeBufferArray(scip, &idx);
8755 *
8756 * return SCIP_OKAY;
8757 * }
8758 * \endcode
8759 */
8760
8761/**@page LICENSE License
8762 *
8763 * \verbinclude LICENSE
8764 */
8765
8766/**@page FAQ Frequently Asked Questions (FAQ)
8767 * \htmlinclude faq/faq.inc
8768 */
8769
8770
8771/**@page PARAMETERS List of all SCIP parameters
8772 *
8773 * This page list all parameters of the current SCIP version. This list can
8774 * easily be generated by SCIP via the interactive shell using the following command:
8775 *
8776 * <code>SCIP&gt; set save &lt;file name&gt;</code>
8777 *
8778 * or via the function call:
8779 *
8780 * <code>SCIP_CALL( SCIPwriteParams(scip, &lt;file name&gt;, TRUE, FALSE) );</code>
8781 *
8782 * \verbinclude parameters.set
8783 */
8784
8785/**@page INTERFACES Interfaces
8786 *
8787 * There are several ways of accessing the \SCIP Optimization Suite from other software packages or programming
8788 * platforms.
8789 *
8790 *
8791 * @section FILEFORMATS File formats
8792 *
8793 * The easiest way to load a problem into SCIP is via an input file, given in a format that SCIP can parse directly,
8794 * see \ref SHELL "the tutorial on how to use the interactive shell".
8795 * \SCIP is capable of reading more than ten different file formats, including formats for nonlinear
8796 * problems and constraint programs. This gives researchers from different communities an easy access to the
8797 * \SCIP Optimization Suite. See also the \ref AVAILABLEFORMATS "list of readable file formats".
8798 *
8799 * @section C_API C API
8800 *
8801 * The main access point for \SCIP is its API to C. Please refer to the \ref PUBLICAPI documentation
8802 * for further details.
8803 *
8804 * @section CPLUSPLUS C++ wrapper classes
8805 *
8806 * Since \SCIP is written in C, its callable library can be directly accessed from C++. If a user wants to program own
8807 * plugins in C++, there are wrapper classes for all different types of plugins available in the <code>src/objscip</code>
8808 * directory of the \SCIP standard distribution. SCIP provides several examples that were written in C++, see
8809 * \ref EXAMPLES "Examples".
8810 *
8811 * @section SCIPINTERFACES Interfaces for other programming languages
8812 *
8813 * Interfaces for other programming languages are developed and maintained independently from the SCIP Optimization Suite
8814 * on <a href="https://github.com/scipopt">GitHub</a> in order to provide extensions and patches faster
8815 * and to collaborate on them more easily.
8816 *
8817 * - <a href="https://github.com/scipopt/PySCIPOpt">PySCIPOpt</a> provides an extensive open-source interface for Python.
8818 * PySCIPOpt can be installed via <a href="https://anaconda.org/conda-forge/pyscipopt">conda-forge</a>,
8819 * which automatically includes \SCIP.
8820 * PySCIPOpt uses wrappers to allow users to build
8821 * their own plugins without accessing the C code of \SCIP itself.
8822 * Since Python is one of the most commonly used programming languages, especially in the field of
8823 * machine learning, the API gives easy access to the solvers functionality to incorporate \SCIP
8824 * into any python project pipeline, extract data for further analysis and computation as well as allow
8825 * customizing the solving process.
8826 * - <a href="https://github.com/scipopt/SCIP.jl">SCIP.jl</a> is a
8827 * Julia interface that exposes an API identical to the SCIP-C_API and implements the
8828 * MathOptInterface used by most constrained solvers in Julia.
8829 * It can be accessed through the Julia package manager and will install a pre-built version of
8830 * \SCIP if none is provided by the user.
8831 * - There is a <a href="https://github.com/scipopt/MatlabSCIPInterface">Matlab interface</a>
8832 * to use SCIP and SCIP-SDP from Matlab and Octave.
8833 * - <a href="https://github.com/scipopt/JSCIPOpt">JSCIPOpt</a> is an interface for Java.
8834 * - <a href="https://github.com/scipopt/russcip">Russcip</a> is an interface for Rust.
8835 * - <a href="https://github.com/scipopt/SCIPpp">SCIP++</a> is a modeling interface for C++.
8836 *
8837 * Contributions to these projects are very welcome.
8838 *
8839 * There are also many third-party python interfaces to the \SCIP Optimization Suite, for example:
8840 * - <a href="https://github.com/eomahony/Numberjack">NUMBERJACK</a> is a constraint programming platform implemented in python.
8841 * It supports a variety of different solvers, one of them being the \SCIP Optimization Suite .
8842 * - <a href="http://code.google.com/p/python-zibopt/">python-zibopt</a> was developed
8843 * by Ryan J. O'Neil and is a python extension of the \SCIP Optimization Suite (not maintained anymore).
8844 * - <a href="http://picos.zib.de/">PICOS</a> is a python interface for conic optimization,
8845 * provided by Guillaume Sagnol.
8846 *
8847 * @section MODELLING Modeling languages
8848 *
8849 * A natural way of formulating an optimization problem is to use a modeling language.
8850 * Besides ZIMPL, which is part of the \SCIP Optimization Suite,
8851 * there are several other modeling tools with a direct interface to \SCIP:
8852 *
8853 * - <a href="https://zimpl.zib.de">ZIMPL</a>, a modeling language for constraint programming,
8854 * - both <a href="http://www.ampl.com/">AMPL</a> and <a href="http://www.gams.com">GAMS</a>,
8855 * are well-suited for modeling mixed-integer linear and nonlinear optimization problems,
8856 * - and <a href="https://projects.coin-or.org/Cmpl">CMPL</a> for mixed-integer linear problems.
8857 * - <a href="https://jump.dev/JuMP.jl/stable/">JuMP</a> accesses SCIP through the Julia interface.
8858 * - <a href="http://users.isy.liu.se/johanl/yalmip/pmwiki.php?n=Main.HomePage">YALMIP</a> by Johan L&ouml;fberg provides a
8859 * free modeling language.
8860 *
8861 * The AMPL and ZIMPL interfaces are included in the \SCIP distribution,
8862 * the GAMS interface is available <a href="https://github.com/coin-or/GAMSlinks">here</a>.
8863 *
8864 */
8865
8866 /**@defgroup PUBLICAPI Public API of SCIP
8867 * @brief methods and headers of the public C-API of \SCIP. Please refer to \ref DOC "" for information how to use the reference manual.
8868 *
8869 * \PUBLICAPIDESCRIPTION
8870 *
8871 *
8872 */
8873
8874/**@defgroup PUBLICCOREAPI Core API
8875 * @ingroup PUBLICAPI
8876 * @brief methods and headers of the plugin-independent C-API provided by the \SCIP header file scip.h.
8877 *
8878 * This module comprises methods provided by the header file scip.h. Including this header into a user-written extension
8879 * suffices to have all plugin-independent functionality of \SCIP available. Plugin-independent
8880 * user functionality includes the
8881 *
8882 * - creation of problems that \SCIP should solve
8883 * - fine-grained access to initiate the solving process of \SCIP
8884 * - access to all sorts of solving process statistics
8885 * - commonly used data structures and algorithms
8886 * - the management of plugins
8887 * - ...
8888 *
8889 * In order facilitate the navigation through the core API of \SCIP, it is structured into different modules.
8890 */
8891
8892/**@defgroup TYPEDEFINITIONS Type Definitions
8893 * @ingroup PUBLICCOREAPI
8894 * @brief type definitions and callback declarations
8895 *
8896 * This page lists headers which contain type definitions of callback methods.
8897 *
8898 * All headers below include the descriptions of callback methods of
8899 * certain plugins. For more detail see the corresponding header.
8900 */
8901
8902/**@defgroup PublicProblemMethods Problem Creation
8903 * @ingroup PUBLICCOREAPI
8904 * @brief methods to create a problem that \SCIP should solve
8905 *
8906 * This module summarizes the main methods needed to create a problem for \SCIP, and access its most important members:
8907 * - Declaring, adding, accessing, and changing variables of the problem
8908 * - Declaring, adding, accessing, and changing constraints of the problem
8909 * - Creating, adding, accessing, changing, and checking of solutions to the problem
8910 *
8911 * @note These core methods are not sufficient to create constraints of a certain type that is provided by the default plugins of \SCIP.
8912 * An example would be the creation of a linear constraint for which the methods provided by the
8913 * \ref cons_linear.h "linear constraint handler" must be used. Such methods are provided by the default plugins of \SCIP
8914 * and can be found in the \ref PUBLICPLUGINAPI.
8915 */
8916
8917/**@defgroup GeneralSCIPMethods SCIP
8918 * @ingroup PublicProblemMethods
8919 * @brief methods to manipulate a SCIP object
8920 */
8921
8922/**@defgroup GlobalProblemMethods Global Problem
8923 * @ingroup PublicProblemMethods
8924 * @brief methods to create, read and modify a global problem together with its callbacks
8925 */
8926
8927/**@defgroup PublicVariableMethods Problem Variables
8928 * @ingroup PublicProblemMethods
8929 * @brief public methods for problem variables
8930 */
8931
8932/**@defgroup PublicConstraintMethods Problem Constraints
8933 * @ingroup PublicProblemMethods
8934 * @brief Public methods for constraints
8935 */
8936
8937/**@defgroup PublicSolutionMethods Primal Solution
8938 * @ingroup PublicProblemMethods
8939 * @brief methods to create and change primal solutions of \SCIP
8940 */
8941
8942/**@defgroup CopyMethods Problem Copies
8943 * @ingroup PublicProblemMethods
8944 * @brief methods to copy problems between a source and a target \SCIP
8945 */
8946
8947
8948 /**@defgroup PublicSolveMethods Solving Process
8949 * @ingroup PUBLICCOREAPI
8950 * @brief methods to control the solving process of \SCIP
8951 *
8952 * This large group of methods and modules comprises the solving process related API of \SCIP. This includes
8953 *
8954 * -# changing parameters to control the solver behavior
8955 * -# access search tree related information
8956 * -# access relaxation information
8957 * -# access various solving process statistics
8958 * -# solve auxiliary relaxations and subproblems using LP/NLP diving or probing mode
8959 */
8960
8961/**@defgroup PublicSolvingStatsMethods Solving Statistics
8962 * @ingroup PublicSolveMethods
8963 * @brief methods to query statistics about the solving process
8964 */
8965
8966/**@defgroup ParameterMethods Parameter
8967 * @ingroup PublicSolveMethods
8968 * @brief methods to create, query, and print user parameters
8969 */
8970
8971/**@defgroup PublicEventMethods Event Handling
8972 * @ingroup PublicSolveMethods
8973 * @brief methods to create, catch, process, and drop events during the solving process of \SCIP
8974 *
8975 * Events can only be caught during the operation on the transformed problem.
8976 * Events on variables can only be caught for transformed variables.
8977 * If you want to catch an event for an original variable, you have to get the corresponding transformed variable
8978 * with a call to SCIPgetTransformedVar() and catch the event on the transformed variable.
8979 */
8980
8981/**@defgroup PublicLPMethods LP Relaxation
8982 * @ingroup PublicSolveMethods
8983 * @brief methods to build and access LP relaxation information
8984 * @see methods to interact with \ref PublicColumnMethods "LP columns" and \ref PublicRowMethods "LP rows"
8985 */
8986
8987/**@defgroup PublicColumnMethods LP Column
8988 * @ingroup PublicLPMethods
8989 * @brief public methods for LP columns
8990 */
8991
8992/**@defgroup PublicRowMethods LP Row
8993 * @ingroup PublicLPMethods
8994 * @brief public methods for LP rows
8995 */
8996
8997/**@defgroup PublicCutMethods Cuts and Cutpools
8998 * @ingroup PublicLPMethods
8999 * @brief common methods used to manipulate, generate, and strengthen cuts and to organize the cutpool
9000 */
9001
9002/**@defgroup PublicLPDivingMethods LP Diving
9003 * @ingroup PublicLPMethods
9004 * @brief methods to initiate and conduct LP diving
9005 */
9006
9007/**@defgroup PublicNLPMethods NLP Relaxation
9008 * @ingroup PublicSolveMethods
9009 * @brief methods for the nonlinear relaxation
9010 */
9011
9012/**@defgroup PublicNLRowMethods Nonlinear Rows
9013 * @ingroup PublicNLPMethods
9014 * @brief methods for the creation and interaction with rows of the NLP relaxation
9015 */
9016
9017/**@defgroup PublicNLPDiveMethods NLP Diving
9018 * @ingroup PublicNLPMethods
9019 * @brief methods to initiate and conduct NLP Diving
9020 */
9021
9022/**@defgroup PublicConflictMethods Conflict Analysis
9023 * @ingroup PublicSolveMethods
9024 * @brief public methods for conflict analysis
9025 */
9026
9027/**@defgroup PublicBranchingMethods Branching
9028 * @ingroup PublicSolveMethods
9029 * @brief methods for branching on LP solutions, relaxation solutions, and pseudo solutions
9030 *
9031 * @see \ref PublicVariableMethods "Public Variable methods" contains some typical variable branching score functions
9032 */
9033
9034/**@defgroup LocalSubproblemMethods Local Subproblem
9035 * @ingroup PublicSolveMethods
9036 * @brief methods to query information about or strengthen the problem at the current local search node
9037 */
9038
9039/**@defgroup PublicTreeMethods Search Tree
9040 * @ingroup PublicSolveMethods
9041 * @brief methods to query search tree related information
9042 * @see \ref PublicNodeMethods "Public methods for nodes"
9043 */
9044
9045/**@defgroup PublicNodeMethods Nodes
9046 * @ingroup PublicTreeMethods
9047 * @brief methods for nodes of the search tree of \SCIP
9048 */
9049
9050/**@defgroup PublicProbingMethods Probing
9051 * @ingroup PublicSolveMethods
9052 * @brief methods to initiate and control the probing mode of \SCIP
9053 */
9054
9055/**@defgroup PublicReoptimizationMethods Reoptimization
9056 * @ingroup PublicSolveMethods
9057 * @brief methods for reoptimization related tasks
9058 */
9059
9060/** @defgroup DataStructures Data Structures
9061 * @ingroup PUBLICCOREAPI
9062 * @brief commonly used data structures
9063 *
9064 * Below you find a list of available data structures
9065 */
9066
9067/** @defgroup DisjointSet Disjoint Set (Union Find)
9068 * @ingroup DataStructures
9069 * @brief weighted disjoint set (union find) data structure with path compression
9070 *
9071 * Weighted Disjoint Set is a data structure to quickly update and query connectedness information
9072 * between nodes of a graph. Disjoint Set is also known as Union Find.
9073 */
9074
9075/**@defgroup PublicDynamicArrayMethods Dynamic Arrays
9076 * @ingroup DataStructures
9077 * @brief methods for the creation and access of dynamic arrays
9078 */
9079
9080/**@defgroup DirectedGraph Directed Graph
9081 * @ingroup DataStructures
9082 * @brief graph structure with common algorithms for directed and undirected graphs
9083 */
9084
9085/**@defgroup DecompMethods Decomposition data structure
9086 * @ingroup DataStructures
9087 * @brief methods for creating and accessing user decompositions
9088 */
9089
9090/**@defgroup SymGraph Symmetry Detection Graph
9091 * @ingroup DataStructures
9092 * @brief methods for creating and manipulating symmetry detection graphs
9093 *
9094 * Below you find a list of functions to create and manipulate symmetry detection graphs.
9095 */
9096
9097/**@defgroup MiscellaneousMethods Miscellaneous Methods
9098 * @ingroup PUBLICCOREAPI
9099 * @brief commonly used methods from different categories
9100 *
9101 * Below you find a list of miscellaneous methods grouped by different categories
9102 */
9103
9104/**@defgroup PublicValidationMethods Validation
9105 * @ingroup PUBLICCOREAPI
9106 * @brief methods for validating the correctness of a solving process
9107 */
9108
9109/**@defgroup PublicMemoryMethods Memory Management
9110 * @ingroup MiscellaneousMethods
9111 * @brief methods and macros to use the \SCIP memory management
9112 *
9113 * @see \ref MEMORY "Using the memory functions of SCIP" for more information
9114 */
9115
9116/**@defgroup PublicTimingMethods Timing
9117 * @ingroup MiscellaneousMethods
9118 * @brief methods for timing
9119 */
9120
9121/**@defgroup PublicBanditMethods Bandit Algorithms
9122 * @ingroup MiscellaneousMethods
9123 * @brief methods for bandit algorithms
9124 */
9125
9126
9127
9128/**@defgroup DebugSolutionMethods Debug Solution
9129 * @ingroup PUBLICCOREAPI
9130 * @brief methods to control the SCIP debug solution mechanism, see also \ref DEBUG
9131 */
9132
9133/**@defgroup MessageOutputMethods Messaging
9134 * @ingroup PUBLICCOREAPI
9135 * @brief message output methods
9136 */
9137
9138/**@defgroup PluginManagementMethods Methods for managing plugins
9139 * @ingroup PUBLICCOREAPI
9140 * @brief Methods for the inclusion and management of SCIP plugins and callback functions
9141 *
9142 */
9143
9144/**@defgroup PublicBendersMethods Benders' decomposition
9145 * @ingroup PluginManagementMethods
9146 * @brief methods for Benders' decomposition plugins
9147 */
9148
9149/**@defgroup PublicBenderscutsMethods Benders' decomposition cuts
9150 * @ingroup PluginManagementMethods
9151 * @brief methods for Benders' decomposition cuts plugins
9152 */
9153
9154/**@defgroup PublicBranchRuleMethods Branching Rules
9155 * @ingroup PluginManagementMethods
9156 * @brief methods for branching rule plugins
9157 */
9158
9159/**@defgroup PublicCompressionMethods Tree Compression
9160 * @ingroup PluginManagementMethods
9161 * @brief public methods for tree compressions
9162 */
9163
9164/**@defgroup PublicConflicthdlrMethods Conflict Analysis
9165 * @ingroup PluginManagementMethods
9166 * @brief public methods for conflict handlers
9167 */
9168
9169/**@defgroup PublicConshdlrMethods Constraint handlers
9170 * @ingroup PluginManagementMethods
9171 * @brief methods for constraint handlers
9172 */
9173
9174/**@defgroup PublicCutSelectorMethods Cut Selector
9175 * @ingroup PluginManagementMethods
9176 * @brief methods for cut selectors
9177 */
9178
9179/**@defgroup PublicDialogMethods Dialogs
9180 * @ingroup PluginManagementMethods
9181 * @brief public methods for user interface dialogs
9182 */
9183
9184/**@defgroup PublicDisplayMethods Displays
9185 * @ingroup PluginManagementMethods
9186 * @brief methods for the inclusion and access of display plugins
9187 */
9188
9189/**@defgroup PublicEventHandlerMethods Event Handler
9190 * @ingroup PluginManagementMethods
9191 * @brief methods for event handlers
9192 */
9193
9194/**@defgroup PublicExprHandlerMethods Expression Handler
9195 * @ingroup PluginManagementMethods
9196 * @brief methods for expression handlers
9197 */
9198
9199/**@defgroup PublicHeuristicMethods Primal Heuristics
9200 * @ingroup PluginManagementMethods
9201 * @brief methods for primal heuristic plugins
9202 */
9203
9204/**@defgroup PublicDivesetMethods Dive sets
9205 * @ingroup PublicSpecialHeuristicMethods
9206 * @brief methods for dive sets to control the generic diving algorithm
9207 */
9208
9209/**@defgroup PublicNodeSelectorMethods Node Selector
9210 * @ingroup PluginManagementMethods
9211 * @brief methods for node selector plugin management
9212 */
9213
9214/**@defgroup PublicNlhdlrInterfaceMethods Nonlinear Handlers
9215 * @ingroup PluginManagementMethods
9216 * @brief methods for the management of nonlinear handlers
9217 */
9218
9219/**@defgroup PublicPresolverMethods Presolver
9220 * @ingroup PluginManagementMethods
9221 * @brief methods for presolver plugins
9222 */
9223
9224/**@defgroup PublicPricerMethods Pricer
9225 * @ingroup PluginManagementMethods
9226 * @brief methods to include and access pricer plugins of \SCIP
9227 */
9228
9229/**@defgroup PublicPropagatorMethods Propagators
9230 * @ingroup PluginManagementMethods
9231 * @brief methods for propagator plugins
9232 */
9233
9234/**@defgroup PublicReaderMethods Reader
9235 * @ingroup PluginManagementMethods
9236 * @brief methods for the inclusion and access to reader plugins of \SCIP
9237 */
9238
9239/**@defgroup PublicRelaxatorMethods Relaxation Handlers
9240 * @ingroup PluginManagementMethods
9241 * @brief public methods for relaxation handlers
9242 */
9243
9244/**@defgroup PublicSeparatorMethods Separators
9245 * @ingroup PluginManagementMethods
9246 * @brief methods for separator plugins
9247 */
9248
9249/**@defgroup PublicTableMethods Tables
9250 * @ingroup PluginManagementMethods
9251 * @brief methods for the inclusion and access of statistics tables
9252 */
9253
9254/**@defgroup PublicConcsolverTypeMethods Concurrent Solver Types
9255 * @ingroup PluginManagementMethods
9256 * @brief methods for concurrent solver type plugins
9257 */
9258
9259/**@defgroup PublicNLPIInterfaceMethods NLP solver interfaces
9260 * @ingroup PluginManagementMethods
9261 * @brief methods for the management of NLP solver interfaces
9262 */
9263
9264/**@defgroup PublicExternalCodeMethods External Codes
9265 * @ingroup PluginManagementMethods
9266 * @brief methods to access information about external codes used by \SCIP
9267 */
9268
9269/**@defgroup PublicParallelMethods Parallel Interface
9270 * @ingroup PUBLICCOREAPI
9271 * @brief methods to construct the parallel interface of \SCIP
9272 */
9273
9274 /**@defgroup PUBLICPLUGINAPI Plugin API of SCIP
9275 * @ingroup PUBLICAPI
9276 * @brief core API extensions provided by the default plugins of \SCIP, includable via scipdefplugins.h.
9277 *
9278 * All default plugins of \SCIP, especially the default \ref CONSHDLRS "constraint handlers", provide
9279 * valuable extensions to the \ref PUBLICCOREAPI "core API" of \SCIP. These methods are made available
9280 * by including scipdefplugins.h to user-written extensions.
9281 *
9282 * For a better overview, this page lists all default plugin headers structured into modules based on their individual
9283 * topic.
9284 *
9285 * All of the modules listed below provide functions that are allowed to be used by user-written extensions of \SCIP.
9286 */
9287 /**@defgroup INTERNALAPI Internal API of SCIP
9288 * @brief internal API methods that should only be used by the core of \SCIP
9289 *
9290 * This page lists the header files of internal API methods. In contrast to the public API, these internal methods
9291 * should not be used by user plugins and extensions of SCIP. Please consult
9292 * \ref PUBLICCOREAPI "the Core API" and \ref PUBLICPLUGINAPI "Plugin API" for the complete API available to user plugins.
9293 *
9294 */
9295
9296/**@defgroup BENDERS Benders' decomposition implementations
9297 * @ingroup PUBLICPLUGINAPI
9298 * @brief methods and files provided by the default Benders' decomposition implementations of \SCIP
9299 *
9300 * A detailed description what a Benders' decomposition implementation does and how to add a Benders' decomposition
9301 * implementations to SCIP can be found
9302 * \ref BENDER "here".
9303 */
9304
9305/**@defgroup BendersIncludes Inclusion methods
9306 * @ingroup BENDERS
9307 * @brief methods to include specific Benders' decomposition implementations into \SCIP
9308 *
9309 * This module contains methods to include specific Benders' decomposition implementations into \SCIP.
9310 *
9311 * @note All default plugins can be included at once (including all Benders' decomposition implementations) using
9312 * SCIPincludeDefaultPlugins()
9313 *
9314 */
9315
9316/**@defgroup BENDERSCUTS Benders' decomposition cut method
9317 * @ingroup PUBLICPLUGINAPI
9318 * @brief methods and files provided by the default Benders' decomposition cut method of \SCIP
9319 *
9320 * A detailed description what a Benders' decomposition cut method does and how to add a Benders' decomposition
9321 * cut method to SCIP can be found
9322 * \ref BENDERSCUT "here".
9323 */
9324
9325/**@defgroup BenderscutIncludes Inclusion methods
9326 * @ingroup BENDERSCUTS
9327 * @brief methods to include specific Benders' decomposition cut methods into \SCIP
9328 *
9329 * This module contains methods to include specific Benders' decomposition cut methods into \SCIP.
9330 *
9331 * @note The Benders' decomposition cut methods are linked to each Benders' decomposition implementation. Thus, the
9332 * default Benders' decomposition implementations automatically include the necessary Benders' decomposition cut
9333 * methods. For custom Benders' decomposition implementations, you can call SCIPincludeDefaultBendersCuts() in the
9334 * SCIPincludeBendersMybenders() include function.
9335 *
9336 */
9337
9338/**@defgroup BRANCHINGRULES Branching Rules
9339 * @ingroup PUBLICPLUGINAPI
9340 * @brief methods and files provided by the default branching rules of \SCIP
9341 *
9342 * A detailed description what a branching rule does and how to add a branching rule to SCIP can be found
9343 * \ref BRANCH "here".
9344 */
9345
9346/**@defgroup BranchingRuleIncludes Inclusion methods
9347 * @ingroup BRANCHINGRULES
9348 * @brief methods to include specific branching rules into \SCIP
9349 *
9350 * This module contains methods to include specific branching rules into \SCIP.
9351 *
9352 * @note All default plugins can be included at once (including all branching rules) using SCIPincludeDefaultPlugins()
9353 *
9354 */
9355
9356/**@defgroup CONSHDLRS Constraint Handlers
9357 * @ingroup PUBLICPLUGINAPI
9358 * @brief methods and files provided by the default constraint handlers of \SCIP
9359 *
9360 * A detailed description what a constraint handler does and how to add a constraint handler to SCIP can be found
9361 * \ref CONS "here".
9362 */
9363
9364/**@defgroup ConshdlrIncludes Inclusion methods
9365 * @ingroup CONSHDLRS
9366 * @brief methods to include specific constraint handlers into \SCIP
9367 *
9368 * This module contains methods to include specific constraint handlers into \SCIP.
9369 *
9370 * @note All default plugins can be included at once (including all default constraint handlers) using SCIPincludeDefaultPlugins()
9371 *
9372 */
9373
9374/**@defgroup CUTSELECTORS Cut Selectors
9375 * @ingroup PUBLICPLUGINAPI
9376 * @brief methods and files provided by the default cut selectors of \SCIP
9377 *
9378 * A detailed description what a cut selector does and how to add a cut selector to SCIP can be found
9379 * \ref CUTSEL "here".
9380 */
9381
9382/**@defgroup CutSelectorIncludes Inclusion methods
9383 * @ingroup CUTSELECTORS
9384 * @brief methods to include specific cut selectors into \SCIP
9385 *
9386 * This module contains methods to include specific cut selectors into \SCIP.
9387 *
9388 * @note All default plugins can be included at once (including all default cut selectors) using SCIPincludeDefaultPlugins()
9389 *
9390 */
9391
9392/**@defgroup DIALOGS Dialogs
9393 * @ingroup PUBLICPLUGINAPI
9394 * @brief methods and files provided by the default dialogs of \SCIP
9395 *
9396 * A detailed description what a dialog does and how to add a dialog to SCIP can be found
9397 * \ref DIALOG "here".
9398 */
9399
9400/**@defgroup DialogIncludes Inclusion methods
9401 * @ingroup DIALOGS
9402 * @brief methods to include specific dialogs into \SCIP
9403 *
9404 * This module contains methods to include specific dialogs into \SCIP.
9405 *
9406 * @note All default plugins can be included at once (including all default dialogs) using SCIPincludeDefaultPlugins()
9407 *
9408 */
9409
9410/**@defgroup DISPLAYS Displays
9411 * @ingroup PUBLICPLUGINAPI
9412 * @brief methods and files provided by the default displays (output columns) of \SCIP
9413 *
9414 * A detailed description what a display does and how to add a display to SCIP can be found
9415 * \ref DISP "here".
9416 *
9417 */
9418
9419/**@defgroup DisplayIncludes Inclusion methods
9420 * @ingroup DISPLAYS
9421 * @brief methods to include specific displays into \SCIP
9422 *
9423 * This module contains methods to include specific displays into \SCIP.
9424 *
9425 * @note All default plugins can be included at once (including all default displays) using SCIPincludeDefaultPlugins()
9426 *
9427 */
9428
9429/**@defgroup EXPRHDLRS Expression Handlers
9430 * @ingroup PUBLICPLUGINAPI
9431 * @brief methods and files provided by the default expressions handlers of \SCIP
9432 */
9433
9434/**@defgroup ExprhdlrIncludes Inclusion methods
9435 * @ingroup EXPRHDLRS
9436 * @brief methods to include specific expression handlers into \SCIP
9437 *
9438 * This module contains methods to include specific expression handlers into \SCIP.
9439 *
9440 * @note All default plugins can be included at once (including all default expression handlers) using SCIPincludeDefaultPlugins()
9441 *
9442 */
9443
9444/**@defgroup EXPRINTS Expression Interpreter
9445 * @ingroup PUBLICPLUGINAPI
9446 * @brief methods and files provided by the default expression interpreters of \SCIP
9447 *
9448 * A detailed description what a expression interpreter does and how to add a expression interpreter to SCIP can be found
9449 * \ref EXPRINT "here".
9450 */
9451
9452/**@defgroup FILEREADERS File Readers
9453 * @ingroup PUBLICPLUGINAPI
9454 * @brief This page contains a list of all file readers which are currently available.
9455 *
9456 * @section AVAILABLEFORMATS List of readable file formats
9457 *
9458 * The \ref SHELL "interactive shell" and the callable library are capable of reading/parsing several different file
9459 * formats.
9460 *
9461 * <table>
9462 * <tr><td>\ref reader_bnd.h "BND format"</td> <td>for variable bounds</td></tr>
9463 * <tr><td>\ref reader_cip.h "CIP format"</td> <td>for SCIP's constraint integer programming format</td></tr>
9464 * <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>
9465 * <tr><td>\ref reader_diff.h "DIFF format"</td> <td>for reading a new objective function for mixed-integer programs</td></tr>
9466 * <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>
9467 * <tr><td>\ref reader_lp.h "LP format"</td> <td>for mixed-integer (quadratically constrained quadratic) programs (CPLEX)</td></tr>
9468 * <tr><td>\ref reader_mps.h "MPS format"</td> <td>for mixed-integer (quadratically constrained quadratic) programs</td></tr>
9469 * <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
9470 * <tr><td>\ref reader_opb.h "OPB format"</td> <td>for pseudo-Boolean optimization instances</td></tr>
9471 * <tr><td>\ref reader_osil.h "OSiL format"</td> <td>for mixed-integer nonlinear programs</td></tr>
9472 * <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>
9473 * <tr><td>\ref reader_sol.h "SOL format"</td> <td>for solutions; XML-format (read-only) or raw SCIP format</td></tr>
9474 * <tr><td>\ref reader_wbo.h "WBO format"</td> <td>for weighted pseudo-Boolean optimization instances</td></tr>
9475 * <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
9476 * programming problems [read only]</td></tr>
9477 * </table>
9478 *
9479 * @section ADDREADER How to add a file reader
9480 *
9481 * A detailed description what a file reader does and how to add a file reader to SCIP can be found
9482 * \ref READER "here".
9483 *
9484 */
9485
9486/**@defgroup FileReaderIncludes Inclusion methods
9487 * @ingroup FILEREADERS
9488 * @brief methods to include specific file readers into \SCIP
9489 *
9490 * This module contains methods to include specific file readers into \SCIP.
9491 *
9492 * @note All default plugins can be included at once (including all default file readers) using SCIPincludeDefaultPlugins()
9493 *
9494 */
9495
9496/**@defgroup PARALLEL Parallel interface methods
9497 * @ingroup INTERNALAPI
9498 * @brief headers and methods for the parallel interface of \SCIP
9499 *
9500 */
9501
9502/**@defgroup PublicSymmetryMethods Symmetry
9503 * @ingroup PUBLICCOREAPI
9504 * @brief methods for symmetry handling
9505 */
9506
9507/**@defgroup FileReaderIncludes Inclusion methods
9508 * @ingroup FILEREADERS
9509 * @brief methods to include specific file readers into \SCIP
9510 *
9511 * This module contains methods to include specific file readers into \SCIP.
9512 *
9513 * @note All default plugins can be included at once (including all default file readers) using SCIPincludeDefaultPlugins()
9514 *
9515 */
9516
9517/**@defgroup LPIS LP Solver Interface
9518 * @ingroup PUBLICPLUGINLPI
9519 * @brief methods and files provided by the LP solver interface of \SCIP
9520 *
9521 * \SCIP uses external tools to solve LP relaxations. The communication
9522 * is realized through an LP interface.
9523 *
9524 * This page lists public interface methods that every LP interface provides.
9525 * Find the concrete implementation for your LP solver
9526 * under "src/lpi/".
9527 *
9528 * @see \ref LPI for a list of available LP solver interfaces
9529 */
9530
9531/**@defgroup NODESELECTORS Node Selectors
9532 * @ingroup PUBLICPLUGINAPI
9533 * @brief methods and files provided by the default node selectors of \SCIP
9534 *
9535 * A detailed description what a node selector does and how to add a node selector to SCIP can be found
9536 * \ref NODESEL "here".
9537 */
9538
9539/**@defgroup NodeSelectorIncludes Inclusion methods
9540 * @ingroup NODESELECTORS
9541 * @brief methods to include specific node selectors into \SCIP
9542 *
9543 * This module contains methods to include specific node selectors into \SCIP.
9544 *
9545 * @note All default plugins can be included at once (including all default node selectors) using SCIPincludeDefaultPlugins()
9546 *
9547 */
9548
9549/**@defgroup NLHDLRS Nonlinear Handlers
9550 * @ingroup PUBLICPLUGINAPI
9551 * @brief methods and files provided by the default nonlinear handlers of \SCIP
9552 */
9553
9554/**@defgroup NlhdlrIncludes Inclusion methods
9555 * @ingroup NLHDLRS
9556 * @brief methods to include specific nonlinear handlers into \SCIP
9557 *
9558 * This module contains methods to include specific nonlinear handlers into \SCIP.
9559 *
9560 * @note All default plugins can be included at once (including all default nonlinear handlers) using SCIPincludeDefaultPlugins()
9561 *
9562 */
9563
9564/**@defgroup NLPIS NLP Solver Interfaces
9565 * @ingroup PUBLICPLUGINAPI
9566 * @brief methods and files provided by the default NLP solver interfaces of \SCIP
9567 *
9568 * A detailed description what a NLP solver interface does and how to add a NLP solver interface to SCIP can be found
9569 * \ref NLPI "here".
9570 */
9571
9572/**@defgroup NLPIIncludes Inclusion methods
9573 * @ingroup NLPIS
9574 * @brief methods to include specific NLP solver interfaces into \SCIP
9575 *
9576 * This module contains methods to include specific NLP solver interfaces into \SCIP.
9577 *
9578 * @note All default plugins can be included at once (including all default NLP solver interfaces) using SCIPincludeDefaultPlugins()
9579 *
9580 */
9581
9582/**@defgroup PRESOLVERS Presolvers
9583 * @ingroup PUBLICPLUGINAPI
9584 * @brief methods and files provided by the default presolvers of \SCIP
9585 *
9586 * A detailed description what a presolver does and how to add a presolver to SCIP can be found
9587 * \ref PRESOL "here".
9588 */
9589
9590/**@defgroup PresolverIncludes Inclusion methods
9591 * @ingroup PRESOLVERS
9592 * @brief methods to include specific presolvers into \SCIP
9593 *
9594 * This module contains methods to include specific presolvers into \SCIP.
9595 *
9596 * @note All default plugins can be included at once (including all default presolvers) using SCIPincludeDefaultPlugins()
9597 *
9598 */
9599
9600/**@defgroup PRICERS Pricers
9601 * @ingroup PUBLICPLUGINAPI
9602 * @brief methods and files provided by the default pricers of \SCIP
9603 *
9604 * Per default there exist no variable pricer. A detailed description what a variable pricer does and how to add a
9605 * variable pricer to SCIP can be found \ref PRICER "here".
9606 */
9607
9608/**@defgroup PricerIncludes Inclusion methods
9609* @ingroup PRICERS
9610* @brief methods to include specific pricers into \SCIP
9611*
9612* This module contains methods to include specific pricers into \SCIP.
9613*
9614* @note All default plugins can be included at once using SCIPincludeDefaultPlugins(). There exists no pricer per default.
9615* In order to see examples of variable pricers, please consult the \ref EXAMPLES "Coding Examples" of \SCIP.
9616*
9617*/
9618
9619/**@defgroup PRIMALHEURISTICS Primal Heuristics
9620 * @ingroup PUBLICPLUGINAPI
9621 * @brief methods and files provided by the default primal heuristics of \SCIP
9622 *
9623 * A detailed description what a primal heuristic does and how to add a primal heuristic to SCIP can be found
9624 * \ref HEUR "here".
9625 */
9626
9627/**@defgroup PrimalHeuristicIncludes Inclusion methods
9628 * @ingroup PRIMALHEURISTICS
9629 * @brief methods to include specific primal heuristics into \SCIP
9630 *
9631 * This module contains methods to include specific primal heuristics into \SCIP.
9632 *
9633 * @note All default plugins can be included at once (including all default primal heuristics) using SCIPincludeDefaultPlugins()
9634 *
9635 */
9636
9637/**@defgroup PROPAGATORS Propagators
9638 * @ingroup PUBLICPLUGINAPI
9639 * @brief methods and files provided by the default propagators of \SCIP
9640 *
9641 * A detailed description what a propagator does and how to add a propagator to SCIP can be found
9642 * \ref PROP "here".
9643 */
9644
9645/**@defgroup PropagatorIncludes Inclusion methods
9646 * @ingroup PROPAGATORS
9647 * @brief methods to include specific propagators into \SCIP
9648 *
9649 * This module contains methods to include specific propagators into \SCIP.
9650 *
9651 * @note All default plugins can be included at once (including all default propagators) using SCIPincludeDefaultPlugins()
9652 *
9653 */
9654
9655/**@defgroup RELAXATORS Relaxation Handlers
9656 * @ingroup PUBLICPLUGINAPI
9657 * @brief methods and files provided by the default relaxation handlers of \SCIP
9658 *
9659 * A detailed description what a relaxation handler does and how to add a relaxation handler to SCIP can be found
9660 * \ref RELAX "here". Note that the linear programming relaxation is not implemented via the relaxation handler plugin.
9661 * Per default no relaxation handler exists in SCIP. However, there are two relaxation handlers in the
9662 * \ref RELAXATOR_MAIN "Relaxator example".
9663 */
9664
9665/**@defgroup SEPARATORS Separators
9666 * @ingroup PUBLICPLUGINAPI
9667 * @brief methods and files provided by the default separators of \SCIP
9668 *
9669 * A detailed description what a separator does and how to add a separator to SCIP can be found
9670 * \ref SEPA "here".
9671 */
9672
9673/**@defgroup SeparatorIncludes Inclusion methods
9674 * @ingroup SEPARATORS
9675 * @brief methods to include specific separators into \SCIP
9676 *
9677 * This module contains methods to include specific separators into \SCIP.
9678 *
9679 * @note All default plugins can be included at once (including all default separators) using SCIPincludeDefaultPlugins()
9680 *
9681 */
9682
9683/**@defgroup TABLES Tables
9684 * @ingroup PUBLICPLUGINAPI
9685 * @brief methods and files provided by the default statistics tables of \SCIP
9686 *
9687 * A detailed description what a table does and how to add a table to SCIP can be found
9688 * \ref TABLE "here".
9689 *
9690 */
9691
9692/**@defgroup TableIncludes Inclusion methods
9693 * @ingroup TABLES
9694 * @brief methods to include specific tables into \SCIP
9695 *
9696 * This module contains methods to include specific statistics tables into \SCIP.
9697 *
9698 * @note All default plugins can be included at once (including all default statisticstables) using SCIPincludeDefaultPlugins()
9699 *
9700 */
9701
9702/**@defgroup PublicToleranceMethods Computations With Tolerances
9703 * @ingroup NumericalMethods
9704 * @brief methods used by the majority of operations involving floating-point computations in \SCIP
9705 *
9706 * - query the numerical tolerances of \SCIP, as well as special values such as infinity.
9707 * - change tolerances inside relaxations
9708 * - epsilon-comparison methods for floating point numbers
9709 */
9710
9711/** @defgroup CFILES Implementation files (.c files)
9712 * @brief implementation files (.c files) of the SCIP core and the default plugins
9713 *
9714 * The core provides the functionality for creating problems, variables, and general constraints.
9715 * The default plugins of SCIP provide a mix of public API function and private, static function and callback declarations.
9716 */
9717
9718/** @defgroup DEFPLUGINS SCIP Default Plugins
9719 * @ingroup CFILES
9720 * @brief implementation files (.c files) of the SCIP default plugins
9721 *
9722 * The SCIP default plugins provide a mix of public API function and private, static function and callback declarations.
9723 */
9724
9725/** @defgroup OTHER_CFILES Other implementation files of SCIP
9726 * @ingroup CFILES
9727 * @brief other implementation files of SCIP
9728 *
9729 * Relevant core and other functionality of SCIP.
9730 */