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.
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:
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
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.
378 * - @subpage TEST "How to run automated tests with SCIP"
379 * - @subpage COUNTER "How to use SCIP to count feasible solutions"
380 * - @subpage REOPT "How to use reoptimization in SCIP"
381 * - @subpage CONCSCIP "How to use the concurrent solving mode in SCIP"
382 * - @subpage DECOMP "How to provide a problem decomposition"
383 * - @subpage BENDDECF "How to use the Benders' decomposition framework"
384 * - @subpage TRAINESTIMATION "How to train custom tree size estimation for SCIP"
385 * - @subpage SYMMETRY "How to use symmetry handling in SCIP"
386 * - @subpage PROBINGDIVING "How to use probing and diving mode"
387 */
388
389/**@page AUTHORS SCIP Authors
390 *
391 * A list of all current and former developers as well as contributors can
392 * be found on the
393 * <a class="el" href="http://scipopt.org/#developers">Main Web Page</a>.
394 *
395 */
396
397/**@page EXTERNALDOC Links to external documentation
398 *
399 * <a class="el" href="https://www.cgudapati.com/integer-programming/2019/12/15/Getting-Started-With-SCIP-Optimization-Suite.html">Getting Started with SCIP optimization in C++: A toy example</a> by Chaitanya Gudapati.
400 *
401 */
402
403/**@page CHG Release notes and changes between different versions of SCIP
404 *
405 * New features, peformance improvements, and interface changes between different versions of SCIP are documented in the
406 * release notes:
407 *
408 * - \subpage RN9 "SCIP 9"
409 * - \subpage RN8 "SCIP 8"
410 * - \subpage RN70 "SCIP 7.0"
411 * - \subpage RN60 "SCIP 6.0"
412 * - \subpage RN50 "SCIP 5.0"
413 * - \subpage RN40 "SCIP 4.0"
414 * - \subpage RN32 "SCIP 3.2"
415 * - \subpage RN31 "SCIP 3.1"
416 * - \subpage RN30 "SCIP 3.0"
417 * - \subpage RN21 "SCIP 2.1"
418 * - \subpage RN20 "SCIP 2.0"
419 * - \subpage RN12 "SCIP 1.2"
420 * - \subpage RN11 "SCIP 1.1"
421 * - \subpage RN10 "SCIP 1.0"
422 * - \subpage RN09 "SCIP 0.9"
423 * - \subpage RN08 "SCIP 0.8"
424 * - \subpage RN07 "SCIP 0.7"
425 *
426 */
427
428/**@page WHATPROBLEMS What types of optimization problems does SCIP solve?
429 *
430 * As a stand-alone solver, \SCIP can solve mixed-integer nonlinear programs \b (MINLPs), to which it applies
431 * an LP based spatial branch-and-cut algorithm. This method is guaranteed to solve bounded MINLPs
432 * within a given numerical tolerance in a finite amount of time. In particular, \SCIP is a stand-alone
433 * solver for mixed-integer linear programs \b (MIPs).
434 *
435 * As a framework, \SCIP also provides the tools to solve constraint optimization problems defined over
436 * integer and continuous variables. Therefore, the design of \SCIP
437 * supports the easy integration of constraints of arbitrary type into the solver.
438 * More precisely, \SCIP can handle the class of constraint integer programs \b (CIPs), which are constraint optimization problems
439 * that become linear programs (LPs) after the integer variables are fixed.
440 *
441 * @section PROBLEMCLASSES Some important subclasses of CIP and MINLP
442 *
443 * The following table gives a non-exhaustive list of common types of mathematical optimization problems that can be solved
444 * through \SCIP itself or one of its extensions. Some recommendations are given on how to compile \SCIP for a
445 * certain problem class and how make best use of \SCIP. The file format column gives some common file
446 * formats for every class. Note that since some of the mentioned problem classes are more general than others (like
447 * every LP is a MIP is an MINLP), the formats for the superclass should always work just as fine, although they
448 * may be less common for the class at hand.
449 *
450 * Please see also the pages on \ref EXAMPLES "SCIP Examples" and \ref APPLICATIONS "SCIP Applications" to learn more on how
451 * to extend \SCIP for a particular MIP, MINLP, or CIP application.
452 * All examples and applications use the C or C++ APIs of \SCIP. Please have a look at \ref INTERFACES "SCIP interfaces"
453 * to see how to use \SCIP from within other programming languages.
454 *
455 * <table class="types">
456 * <caption align="top">Some problem classes that can be solved by \SCIP</caption>
457 * <tr style="border-bottom: medium solid black;">
947 * A stochastic programming problem that demonstrates the use of the Benders' decomposition framework within SCIP.
948 * </td>
949 * </tr>
950 * </table>
951 */
952
953/** @page APPLICATIONS Application projects
954 *
955 * There are several extensions of \SCIP for particular applications included in the release. They are contained in the "applications" directory
956 * in the source code distribution.
957 *
958 * <table>
959 * <tr>
960 * <td>
961 * @subpage COLORING_MAIN
962 * </td>
963 * <td>
964 * An implementation of the column generation approach for graph coloring of Mehrotra and Trick.
965 * </td>
966 * </tr>
967 * <tr>
968 * <td>
969 * @subpage CYCLECLUSTERING_MAIN
970 * </td>
971 * <td>
972 * Branch-and-cut implementation of a graph partitioning problem used for Markov state models.
973 * </td>
974 * </tr>
975 * <tr>
976 * <td>
977 * @subpage MINIISC_MAIN
978 * </td>
979 * <td>
980 * A solver that computes irreducible infeasible subsystems using Benders decomposition
981 * </td>
982 * </tr>
983 * <tr>
984 * <td>
985 * @subpage RINGPACKING_MAIN "Ringpacking"
986 * </td>
987 * <td>
988 * An implementation of the column generation approach for the Ringpacking Problem. It includes a customized reader,
989 * (global) problem data, variable data, and constraint handler.
990 * </td>
991 * </tr>
992 * <tr>
993 * <td>
994 * @subpage SCHEDULER_MAIN
995 * </td>
996 * <td>
997 * A solver for scheduling problems.
998 * </td>
999 * </tr>
1000 * </table>
1001 *
1002 */
1003
1004
1005/**@page SHELL Tutorial: the interactive shell
1006 *
1007 * If you are using \SCIP as a black box solver, here you will find some tips and tricks what you can do.
1008 *
1009 * @section TUTORIAL_OPTIMIZE Read and optimize a problem instance
1013 * First of all, we need a \SCIP binary and an example problem file to work with.
1014 * For installation we refer you to the \ref INSTALL section.
1015 *
1016 * Therefore, you can either download the \SCIP standard distribution (which includes problem files) and compile it on your own or you can download a
1017 * precompiled binary and an example problem separately. \SCIP can read files in LP, MPS, ZPL, WBO, FZN, PIP, OSiL, and
1018 * other formats (see \ref FILEREADERS).
1019 *
1020 * If you want to download the source code of the \SCIP standard distribution, we recommend to go to the <a
1021 * href="https://scipopt.org/#download">SCIP download section</a>, download the latest release,
1022 * inflate the tarball (e.g., with "tar xzf scipoptsuite-[version].tgz"), and follow the instructions
1023 * in the INSTALL file. The instance stein27, which will serve as an example in this tutorial, can be found under
1043 * Okay, let's solve the example instance... use "read check/instances/MIP/stein27.fzn" (or the problem file of your choice) to parse the instance file, "optimize" to solve it and "display
1044 * solution" to show the nonzero variables of the best found solution.
1160/**@page DOC How to search the documentation and source files structure for public interface methods
1161 *
1162 * If you are looking for a method in order to perform a specific task, the public \ref PUBLICAPI "SCIP C-API" is the place to look.
1163 * - It contains interface methods for all SCIP structs, both in the solver core or in one of the plugins.
1164 * - Plugins are mostly independent from each other, so to use them it is usually enough to browse the \ref PUBLICCOREAPI "Core API".
1165 * - If you want to add your own plugins, see the \ref HOWTOADD pages for exhaustive information for each plugin type.
1166 * - If you are learning SCIP with a concrete project in mind, looking at the available \ref EXAMPLES page may help you
1167 * getting started.
1168 * - See also \ref START "How to start a new project"
1169 *
1170 * Header file names of SCIP obey a consistent naming scheme: Type definitions and related objects such as enums are found in headers starting with "type_",
1171 * such as \ref type_var.h , which contains enums and type definitions related to \ref PublicVariableMethods "SCIP problem variables".
1172 * Definitions of the actual structs can be found in separate header files starting with "struct_".
1173 * All method definitions of the public SCIP API are split across header files starting with "pub_" such as \ref pub_cons.h
1174 * or headers starting with "scip_" such as \ref scip_cons.h .
1175 * The latter headers starting with "scip_" contain more complex methods, which always receive a scip pointer as first argument.
1176 * Those methods may affect several individual components controlled by SCIP. Such a method is SCIPbranchVar(), which
1177 * affects the search tree, which is controlled by SCIP itself and not meant to be accessed by user plugins.
1178 *
1179 * It should be sufficient to include scip/scip.h and scip/scipdefplugins.h for having all
1180 * needed functionality available in a project.
1181 *
1182 * If, for example, you are looking for information on how to create a problem instance, here are some steps you can take:
1183 *
1184 * 1. Browse the SCIP Core API and follow the path \ref PUBLICAPI > \ref PUBLICCOREAPI > \ref PublicProblemMethods > \ref GlobalProblemMethods > SCIPcreateProb()
1185 * 2. Here you can find information on the function's return value, preconditions, postconditions, parameters, as well as related functions.
1186 * 3. If you are unsure of how to use some of the parameters, it is worth looking for a basic version of the function.
1187 * This and other related functions may be found by either browsing neighboring functions and groups in the navigation tree to the left, or in the
1188 * 'References' and 'Referenced by' section of the function documentation. In this case, you can find `SCIPcreateProbBasic()`.
1189 *
1190 * The opposite case is that you already know the name of a function as, e.g., SCIPbranchVar().
1191 *
1192 * 1. Type the name of the function into the search bar to find the function documentation.
1193 * 2. In addition, you can find related methods by browsing the neighboring functions of the same group.
1194 * 3. In this example, you may now learn about SCIPgetNLPBranchCands() to query all integer
1195 * variables with fractional LP solution value, which are good candidates for classical branching on variables.
1196 *
1197 * Note that the \ref INTERNALAPI "private SCIP API" contains more complex functions and data structures that fill specialized roles and
1198 * is only for developers.
1199 * Those functions are **not** exported to the library and are therefore **not available in user projects** using the \ref PUBLICAPI "public SCIP API".
1310 * \par LINCONSUPGD_PRIORITY: priority of the constraint handler for upgrading of linear constraints
1311 * This property is only needed if a certain linear constraint can be upgraded to a more specific one. In one of
1312 * the first presolving rounds SCIP tries to upgrade linear constraints to more specialized constraints, such as
1313 * knapsack constraints. The upgrading calls are processed in the order of decreasing priority.
1314 *
1315 * \par NONLINCONSUPGD_PRIORITY: priority of the constraint handler for upgrading of nonlinear constraints
1316 * This property has the same effect as the LINCONSUPGD_PRIORITY parameter, see above, and should be set whenever
1317 * an upgrade functionality from a general nonlinear constraint to the more specific one is defined.
1318 *
1319 * \par CONSHDLR_SEPAFREQ: the default frequency for separating cuts.
1320 * The separation frequency defines the depth levels at which the constraint handler's separation methods \ref CONSSEPALP
1321 * and \ref CONSSEPASOL are called.
1322 * For example, a separation frequency of 7 means, that the separation callback is executed for subproblems that are
1323 * in depth 0, 7, 14, ... of the branching tree.
1324 * A separation frequency of 0 means, that the separation method is only called at the root node.
1325 * A separation frequency of -1 disables the separation method of the constraint handler.
1326 * \n
1327 * The separation frequency can be adjusted by the user.
1328 * This property of the constraint handler only defines the default value of the frequency.
1329 * If you want to have a more flexible control of when to execute the separation algorithm, you have to assign
1330 * a separation frequency of 1 and implement a check at the beginning of your separation algorithm whether you really
1331 * want to execute the separator or not.
1332 * If you do not want to execute the method, set the result code to SCIP_DIDNOTRUN.
1333 *
1334 * \par CONSHDLR_SEPAPRIORITY: the priority of the constraint handler for separation. (optional: to be set only if the constraint handler supports separation)
1335 * In each separation round during the price-and-cut loop of the subproblem processing or during the separation loop
1336 * of the primal solution separation, the separators and separation methods of the constraint handlers are called in
1337 * a predefined order, which is given by the priorities of the separators and the separation priorities of the
1338 * constraint handlers.
1339 * First, the separators with non-negative priority are called in the order of decreasing priority.
1340 * Next, the separation methods of the different constraint handlers are called in the order of decreasing separation
1341 * priority.
1342 * Finally, the separators with negative priority are called in the order of decreasing priority.
1343 * \n
1344 * The separation priority of the constraint handler should be set according to the complexity of the cut separation
1345 * algorithm and the impact of the resulting cuts:
1346 * Constraint handlers that provide fast algorithms that usually have a high impact (i.e., cut off a large portion of
1347 * the LP relaxation) should have a high priority.
1348 * See \ref CONSSEPALP and \ref CONSSEPASOL for further details of the separation callbacks.
1349 *
1350 * \par CONSHDLR_DELAYSEPA: the default for whether the separation method should be delayed, if other separators found cuts.
1351 * If the constraint handler's separation method is marked to be delayed, it is only executed after no other separator
1352 * or constraint handler found a cut during the price-and-cut loop.
1353 * If the separation method of the constraint handler is very expensive, you may want to mark it to be delayed until all
1354 * cheap separation methods have been executed.
1355 *
1356 * \par CONSHDLR_PROPFREQ: the default frequency for propagating domains.
1357 * This default frequency has the same meaning as the CONSHDLR_SEPAFREQ with respect to the domain propagation
1358 * callback of the constraint handler.
1359 * A propagation frequency of 0 means that propagation is only applied in preprocessing and at the root node.
1360 * A propagation frequency of -1 disables the propagation method of the constraint handler.
1361 *
1362 * \par CONSHDLR_DELAYPROP: the default for whether the propagation method should be delayed, if other propagators found reductions.
1363 * This property is analogous to the DELAYSEPA flag, but deals with the propagation method of the constraint handler.
1364 *
1365 * \par CONSHDLR_PROP_TIMING: the propagation timing mask of the constraint handler.
1366 * SCIP calls the domain propagation routines at different places in the node processing loop.
1367 * This property indicates at which places the propagation routine of the constraint handler is called.
1368 * Possible values are defined in type_timing.h and can be concatenated, e.g., as in SCIP_PROPTIMING_ALWAYS.
1369 *
1370 * \par CONSHDLR_PRESOLTIMING: the timing of the constraint handler's presolving method (FAST, MEDIUM, or EXHAUSTIVE).
1371 * Every presolving round starts with the FAST presolving methods. MEDIUM presolvers are only called, if FAST presolvers did not find
1372 * enough reductions in this round so far, and EXHAUSTIVE presolving steps are only performed if all presolvers called before
1373 * in this round were unsuccessful.
1374 * Presolving methods should be assigned a timing based on how expensive they are, e.g., presolvers that provide fast algorithms that
1375 * usually have a high impact (i.e., remove lots of variables or tighten bounds of many variables) should have a timing FAST.
1376 * If a presolving method implements different algorithms of different complexity, it may also get multiple timings and check the timing
1377 * internally in the \ref CONSPRESOL callback to decide which algorithms to run.
1378 *
1379 * \par CONSHDLR_MAXPREROUNDS: the default maximal number of presolving rounds the constraint handler participates in.
1380 * The preprocessing is executed in rounds.
1381 * If enough changes have been applied to the model, an additional preprocessing round is performed.
1382 * The MAXPREROUNDS parameter of a constraint handler denotes the maximal number of preprocessing rounds the constraint
1383 * handler participates in.
1384 * A value of -1 means that there is no limit on the number of rounds.
1385 * A value of 0 means the preprocessing callback of the constraint handler is disabled.
1386 *
1387 *
1388 *
1389 * @section CONS_DATA Constraint Data and Constraint Handler Data
1390 *
1391 * Below the header "Data structures" you can find two structs called "struct SCIP_ConsData" and
1392 * "struct SCIP_ConshdlrData".
1393 * If you are using C++, you only need to define the "struct SCIP_ConsData".
1394 * The constraint handler data must be implemented as member variables of your constraint handler class.
1395 * \n
1396 * The constraint data are the information that is needed to define a single constraint of the constraint handler's
1397 * constraint class.
1398 * For example, the data of a knapsack constraint would consist of a list of variables, a list of weights, and
1399 * the capacity of the knapsack.
1400 * The data of a subtour constraint consists of the graph on which the problem is defined.
1401 * In the graph, each edge should be linked to the corresponding binary problem variable.
1402 * \n
1403 * The constraint handler data are additional variables, that belong to the constraint handler itself and which are
1404 * not specific to a single constraint.
1405 * For example, you can use these data to store parameters of the constraint handler or statistical information.
1406 * The constraint handler data are optional.
1407 * You can leave the struct empty.
1408 *
1409 *
1410 * @section CONS_INTERFACE Interface Methods
1411 *
1412 * At the bottom of "cons_subtour.c" you can find three interface methods, that also appear in "cons_subtour.h".
1413 * These are SCIPincludeConshdlrSubtour(), SCIPcreateConsSubtour(), and SCIPcreateConsSubtourBasic().
1414 * \n
1415 * The method SCIPincludeConshdlrSubtour() only has to be adjusted slightly.
1416 * It is responsible for notifying SCIP of the presence of the constraint handler by calling the method
1417 * SCIPincludeConshdlr().
1418 * It is called by the user, if (s)he wants to include the constraint handler, i.e., if (s)he wants to make
1419 * the constraint handler available to the model, and looks like this:
1420 * \dontinclude src/scip/cons_knapsack.c
1421 * -# If you are using constraint handler data, you have to <b>allocate the memory for the data</b> at this point.
1422 * You also have to initialize the fields in struct SCIP_ConshdlrData afterwards.
1778 * The CONSINITLP callback is executed before the first LP relaxation is solved.
1779 * It should add the LP relaxations of all "initial" constraints to the LP. The method should scan the constraints
1780 * array for constraints that are marked initial via calls to SCIPconsIsInitial() and put the LP relaxation
1781 * of all initial constraints to the LP with calls to SCIPaddCut().
1782 *
1783 * @subsection CONSSEPALP
1784 *
1785 * The CONSSEPALP callback is executed during the price-and-cut loop of the subproblem processing.
1786 * It should try to generate cutting planes for the constraints of the constraint handler in order to separate
1787 * the current LP solution.
1788 * The method is called in the LP solution loop, which means that a valid LP solution exists.
1789 *
1790 * Usually, a separation callback searches and produces cuts, that are added with a call to SCIPaddCut().
1791 * If the cut should be remembered in the global cut pool, it may also call SCIPaddPoolCut().
1792 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
1793 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
1794 * However, the callback may also produce domain reductions or add other constraints.
1795 *
1796 * The CONSSEPALP callback has the following options:
1797 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1798 * - adding an additional constraint (result SCIP_CONSADDED)
1799 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1800 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
1801 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
1802 * (result SCIP_DIDNOTFIND)
1803 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
1804 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
1805 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
1806 *
1807 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1808 * CONSHDLR_SEPAFREQ, CONSHDLR_SEPAPRIORITY, and CONSHDLR_DELAYSEPA, which influence the behaviour of SCIP
1809 * calling CONSSEPALP.
1810 *
1811 * @subsection CONSSEPASOL
1812 *
1813 * The CONSSEPASOL callback is executed during separation loop on arbitrary primal solutions.
1814 * It should try to generate cutting planes for the constraints of the constraint handler in order to separate
1815 * the given primal solution.
1816 * The method is not called in the LP solution loop, which means that there is no valid LP solution.
1817 *
1818 * Usually, a separation callback searches and produces cuts, that are added with a call to SCIPaddCut().
1819 * If the cut should be remembered in the global cut pool, it may also call SCIPaddPoolCut().
1820 * If the cut is constructed via multiple calls to SCIPaddVarToRow(), then performance can be improved by calling
1821 * SCIPcacheRowExtensions() before these additions and SCIPflushRowExtensions() after.
1822 * However, the callback may also produce domain reductions or add other constraints.
1823 *
1824 * The CONSSEPASOL callback has the following options:
1825 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1826 * - adding an additional constraint (result SCIP_CONSADDED)
1827 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1828 * - adding a cutting plane to the LP (result SCIP_SEPARATED)
1829 * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
1830 * (result SCIP_DIDNOTFIND)
1831 * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
1832 * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
1833 * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
1834 *
1835 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1836 * CONSHDLR_SEPAFREQ, CONSHDLR_SEPAPRIORITY, and CONSHDLR_DELAYSEPA, which influence the behaviour of SCIP
1837 * calling CONSSEPASOL.
1838 *
1839 * @subsection CONSPROP
1840 *
1841 * The CONSPROP callback is called during the subproblem processing.
1842 * It should propagate the constraints, which means that it should infer reductions in the variables' local bounds
1843 * from the current local bounds.
1844 * This technique, which is the main workhorse of constraint programming, is called "node preprocessing" in the
1845 * Integer Programming community.
1846 *
1847 * The CONSPROP callback has the following options:
1848 * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1849 * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1850 * - stating that the propagator searched, but did not find domain reductions, cutting planes, or cut constraints
1851 * (result SCIP_DIDNOTFIND)
1852 * - stating that the propagator was skipped (result SCIP_DIDNOTRUN)
1853 * - stating that the propagator was skipped, but should be called again (result SCIP_DELAYED)
1854 *
1855 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1856 * CONSHDLR_PROPFREQ, CONSHDLR_DELAYPROP, and CONSHDLR_PROP_TIMING, which influence the behaviour of SCIP
1857 * calling CONSPROP.
1858 *
1859 * @subsection CONSRESPROP
1860 *
1861 * If the constraint handler should support \ref CONF "conflict analysis", it has to supply a CONSRESPROP method.
1862 * It also should call SCIPinferVarLbCons() or SCIPinferVarUbCons() in domain propagation instead of SCIPchgVarLb() or
1863 * SCIPchgVarUb() in order to deduce bound changes on variables.
1864 * In the SCIPinferVarLbCons() and SCIPinferVarUbCons() calls, the handler provides the constraint that deduced the
1865 * variable's bound change, and an integer value <code>inferinfo</code> that can be arbitrarily chosen.
1866 *
1867 * The propagation conflict resolving method CONSRESPROP must then be implemented to provide the "reasons" for the bound
1868 * changes, i.e., the bounds of variables at the time of the propagation, which forced the constraint to set the
1869 * conflict variable's bound to its current value. It can use the <code>inferinfo</code> tag to identify its own propagation rule
1870 * and thus identify the "reason" bounds. The bounds that form the reason of the assignment must then be provided by
1871 * calls to SCIPaddConflictLb() and SCIPaddConflictUb() in the propagation conflict resolving method.
1872 *
1873 * <b>Note:</b> The fact that <code>inferinfo</code> is an integer, as opposed to an arbitrary data object, is a compromise between space and speed. Sometimes a propagator would
1874 * need more information to efficiently infer the original propagation steps that lead to the conflict. This would,
1875 * however, require too much space. In the extreme, the original propagation steps have to be repeated.
1876 *
1877 * For example, the \ref cons_logicor.h "logicor constraint" \f$c = x \vee y \vee z\f$ fixes variable \f$z\f$ to TRUE (i.e., changes the lower
1878 * bound of \f$z\f$ to 1.0), if both, \f$x\f$ and \f$y\f$, are assigned to FALSE (i.e., if the upper bounds of these
1879 * variables are 0.0). It uses <code>SCIPinferVarLbCons(scip, z, 1.0, c, 0)</code> to apply this assignment (an
1880 * inference information tag is not needed by the constraint handler and is set to 0). In the conflict analysis, the
1881 * constraint handler may be asked to resolve the lower bound change on \f$z\f$ with constraint \f$c\f$, that was
1882 * applied at a time given by a bound change index "bdchgidx". With a call to <code>SCIPvarGetLbAtIndex(z,
1883 * bdchgidx)</code>, the handler can find out, that the lower bound of variable \f$z\f$ was set to 1.0 at the given
1884 * point of time, and should call <code>SCIPaddConflictUb(scip, x, bdchgidx)</code> and <code>SCIPaddConflictUb(scip, y,
1885 * bdchgidx)</code> to tell SCIP, that the upper bounds of \f$x\f$ and \f$y\f$ at this point of time were the reason for
1886 * the deduction of the lower bound of \f$z\f$.
1887 *
1888 * If conflict analysis should not be supported, the method has to set the result code to SCIP_DIDNOTFIND. Although
1889 * this is a viable approach to circumvent the implementation of the usually rather complex conflict resolving method, it
1890 * will make the conflict analysis less effective. We suggest to first omit the conflict resolving method and check how
1891 * effective the \ref CONSPROP "propagation method" is. If it produces a lot of propagations for your application, you definitely should
1892 * consider implementing the conflict resolving method.
1893 *
1894 * @subsection CONSPRESOL
1895 *
1896 * The CONSPRESOL callback is called during preprocessing.
1897 * It should try to tighten the domains of the variables, tighten the coefficients of the constraints of the constraint
1898 * handler, delete redundant constraints, aggregate and fix variables if possible, and upgrade constraints to more
1899 * specific types.
1900 *
1901 * If the CONSPRESOL callback applies changes to the constraint data, you also have to implement the \ref CONSTRANS callback
1902 * in order to copy the constraint data to the transformed problem space and protect the original problem from the
1903 * preprocessing changes.
1904 *
1905 * To inform SCIP that the presolving method found a reduction the result pointer has to be set in a proper way.
1906 * The following options are possible:
1907 *
1908 * - SCIP_UNBOUNDED : at least one variable is not bounded by any constraint in objective direction
1909 * - SCIP_CUTOFF : at least one constraint is infeasible in the variable's bounds
1910 * - SCIP_SUCCESS : the presolver found a reduction
1911 * - SCIP_DIDNOTFIND : the presolver searched, but did not find a presolving change
1912 * - SCIP_DIDNOTRUN : the presolver was skipped
1913 * - SCIP_DELAYED : the presolver was skipped, but should be called again
1914 *
1915 * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1916 * CONSHDLR_PRESOLTIMING and CONSHDLR_MAXPREROUNDS, which influence the behaviour of SCIP
1917 * calling CONSPRESOL.
1918 *
1919 * @subsection CONSACTIVE
1920 *
1921 * The CONSACTIVE callback method is called each time a constraint of the constraint handler is activated.
1922 * For example, if a constraint is added locally to a subproblem, the CONSACTIVE callback is called whenever the
1923 * search enters the subtree where the constraint exists.
1924 *
1925 * @subsection CONSDEACTIVE
1926 *
1927 * The CONSDEACTIVE callback method is called each time a constraint of the constraint handler is deactivated.
1928 * For example, if a constraint is added locally to a subproblem, the CONSDEACTIVE callback is called whenever the
1929 * search leaves the subtree where the constraint exists.
1930 *
1931 * @subsection CONSENABLE
1932 *
1933 * The CONSENABLE callback method is called each time a constraint of the constraint handler is enabled.
1934 * Constraints might be active without being enabled. In this case, only the feasibility checks are executed,
1935 * but domain propagation and separation is skipped.
1936 *
1937 * @subsection CONSDISABLE
1938 *
1939 * The CONSDISABLE callback method is called each time a constraint of the constraint handler is disabled.
1940 *
1941 * @subsection CONSPRINT
1942 *
1943 * The CONSPRINT callback method is called, when the user asks SCIP to display the problem to the screen
1944 * or save the problem into a file. This is, however, only the case if the user requested the CIP format.
1945 * For more details about reading and writing with SCIP we refer to the \ref READER "file readers". In this
1946 * callback method the constraint handler should display the data of the constraint in an appropriate form.
1947 * The output format that is defined by the CONSPRINT callbacks is called CIP format.
1948 * In later versions of SCIP, the constraint handlers should also be able to parse (i.e., read) constraints
1949 * which are given in CIP format.
1950 *
1951 * @subsection CONSCOPY
1952 *
1953 * The CONSCOPY callback method is used whenever constraints should be copied from one SCIP instance into another SCIP
1954 * instance. This method comes with the necessary parameters to do so, most importantly with a mapping of the variables of the
1955 * source SCIP instance to the corresponding variables of the target SCIP instance, and a mapping for the constraints
1956 * in the same way. For a complete list of all arguments of this callback method see type_cons.h.
1957 *
1958 * To get the corresponding target variable of a given source variable, you can use the variable map directly:
2430 * You also have to initialize the fields in struct SCIP_PresolData afterwards. For freeing the
2431 * presolver data, see \ref PRESOLFREE.
2432 *
2433 * You may also add user parameters for your presolver, see \ref PARAM for how to add user parameters and
2434 * the method SCIPincludePresolTrivial() in src/scip/presol_trivial.c for an example.
2435 *
2436 *
2437 * @section PRESOL_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Presolver
2438 *
2439 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2440 * an operational algorithm.
2441 * They are passed together with the presolver itself to SCIP using SCIPincludePresol() or SCIPincludePresolBasic(),
2442 * see @ref PRESOL_INTERFACE.
2443 *
2444 * Presolver plugins have only one fundamental callback method, namely the @ref PRESOLEXEC method.
2445 * This method has to be implemented for every presolver; the other callback methods are optional.
2446 * In the C++ wrapper class scip::ObjPresol, the scip_exec() method (which corresponds to the PRESOLEXEC callback) is a virtual
2447 * abstract member function.
2448 * You have to implement it in order to be able to construct an object of your presolver class.
2449 *
2450 * Additional documentation for the callback methods, in particular to their input parameters,
2451 * can be found in type_presol.h.
2452 *
2453 * @subsection PRESOLEXEC
2454 *
2455 * The PRESOLEXEC callback is called inside the presolving loop and should perform the actual presolving reductions.
2456 * It should inspect the problem instance at hand and simplify it by tightening bounds of variables, aggregating or fixing
2457 * variables, changing the type of variables, modifying the graph that represents the instance of your application, and
2458 * the like.
2459 *
2460 * Typical methods called by a presolver are, for example, SCIPchgVarType(), SCIPfixVar(), SCIPaggregateVars(), SCIPtightenVarLb(),
2461 * and SCIPtightenVarUb().
2462 *
2463 *
2464 * @section PRESOL_ADDITIONALCALLBACKS Additional Callback Methods of a Presolver
2465 *
2466 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2467 * implemented for most applications, they can be used, for example, to initialize and free private data.
2468 * Additional callbacks can either be passed directly with SCIPincludePresol() to SCIP or via specific
2469 * <b>setter functions</b> after a call of SCIPincludePresolBasic(), see also @ref PRESOL_INTERFACE.
2470 *
2471 * @subsection PRESOLFREE
2472 *
2473 * If you are using presolver data (see \ref PRESOL_DATA and \ref PRESOL_INTERFACE), you have to implement this method in order to free the presolver data.
2474 * This can be done by the following procedure:
2519 * Separators are used to generate cutting planes that strengthen the LP relaxation of the problem formulation, but are
2520 * not required for a completeness and correctness of the model.
2521 * In contrast, constraint-based cutting planes, the second type of cutting planes in SCIP, are separated in the CONSSEPALP and
2522 * CONSSEPASOL callback methods of the constraint handlers, see \ref CONSSEPALP and \ref CONSSEPASOL. These cuts are
2523 * valid inequalities or even facets of the polyhedron described by a single constraint or a subset of the constraints of
2524 * a single constraint class. See also
2525 * "When should I implement a constraint handler, when should I implement a separator?" on \ref FAQ.
2526 * \n
2527 * A complete list of all separators contained in this release can be found \ref SEPARATORS "here".
2528 *
2529 * We now explain how users can add their own separators.
2530 * Take the separator for the class of Gomory mixed integer inequalities (src/scip/sepa_gomory.c) as an example.
2531 * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjSepa wrapper
2532 * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_SEPA... callback methods.
2533 *
2534 * Additional documentation for the callback methods of a separator, in particular for the input parameters,
2535 * can be found in the file type_sepa.h.
2536 *
2537 * Here is what you have to do to implement a separator:
2538 * -# Copy the template files src/scip/sepa_xyz.c and src/scip/sepa_xyz.h into files "sepa_myseparator.c"
2539 * and "sepa_myseparator.h".
2540 \n
2541 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2542 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2543 * -# Use `SCIPincludeSepaMyseparator()` in order to include the separator into your SCIP instance,
2544 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2545 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2546 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myseparator".
2547 * -# Adjust the properties of the separator (see \ref SEPA_PROPERTIES).
2548 * -# Define the separator data (see \ref SEPA_DATA). This is optional.
2549 * -# Implement the interface methods (see \ref SEPA_INTERFACE).
2550 * -# Implement the fundamental callback methods (see \ref SEPA_FUNDAMENTALCALLBACKS).
2551 * -# Implement the additional callback methods (see \ref SEPA_ADDITIONALCALLBACKS). This is optional.
2552 *
2553 *
2554 * @section SEPA_PROPERTIES Properties of a Separator
2555 *
2556 * At the top of the new file "sepa_myseparator.c", you can find the separator properties.
2557 * These are given as compiler defines.
2558 * In the C++ wrapper class, you have to provide the separator properties by calling the constructor
2559 * of the abstract base class scip::ObjSepa from within your constructor.
2560 * The properties you have to set have the following meaning:
2561 *
2562 * \par SEPA_NAME: the name of the separator.
2563 * This name is used in the interactive shell to address the separator.
2564 * Additionally, if you are searching for a separator with SCIPfindSepa(), this name is looked up.
2565 * Names have to be unique: no two separators may have the same name.
2566 *
2567 * \par SEPA_DESC: the description of the separator.
2568 * This string is printed as a description of the separator in the interactive shell.
2569 *
2570 * \par SEPA_PRIORITY: the priority of the separator.
2571 * In each separation round during the price-and-cut loop of the subproblem processing or the separation loop
2572 * of the primal solution separation, the separators and separation methods of the constraint handlers are called in
2573 * a predefined order, which is given by the priorities of the separators and the separation priorities
2574 * of the constraint handlers (see \ref CONS_PROPERTIES).
2575 * First, the separators with non-negative priority are called in the order of decreasing priority.
2576 * Next, the separation methods of the constraint handlers are called in the order of decreasing separation
2577 * priority.
2578 * Finally, the separators with negative priority are called in the order of decreasing priority. An easy way to list the
2579 * priorities of all separators and constraint handlers is to type "display separators" and "display conshdlrs" in
2580 * the interactive shell.
2581 * \n
2582 * The priority of the separator should be set according to the complexity of the cut separation algorithm and the
2583 * impact of the resulting cuts: separators that provide fast algorithms that usually have a high impact (i.e., cut off
2584 * a large portion of the LP relaxation) should have a high priority.
2585 * See \ref SEPAEXECLP and \ref SEPAEXECSOL for further details of the separation callbacks.
2586 *
2587 * \par SEPA_FREQ: the default frequency for separating cuts.
2588 * The frequency defines the depth levels at which the separation methods \ref SEPAEXECLP and \ref SEPAEXECSOL are called.
2589 * For example, a frequency of 7 means, that the separation callback is executed for subproblems that are in depth
2590 * 0, 7, 14, ... of the branching tree. A frequency of 0 means, that the separation method is only called at the root node.
2591 * A frequency of -1 disables the separator.
2592 * \n
2593 * The frequency can be adjusted by the user. This property of the separator only defines the default value of the frequency.
2594 * If you want to have a more flexible control of when to execute the separation algorithm, you have to assign
2595 * a frequency of 1 and implement a check at the beginning of your separation methods whether you really want to execute
2596 * the separation or not. If you do not want to execute it, set the result code of
2597 * \ref SEPAEXECLP and \ref SEPAEXECSOL to SCIP_DIDNOTRUN.
2598 *
2599 * \par SEPA_MAXBOUNDDIST: the default maximal relative distance from the current node's dual bound to primal bound compared to best node's dual bound for applying separation.
2600 * At the current branch-and-bound node, the relative distance from its dual bound (local dual bound)
2601 * to the primal bound compared to the best node's dual bound (global dual bound) is considered. The separation method
2602 * of the separator will only be applied at the current node if this relative distance does not exceed SEPA_MAXBOUNDDIST.
2603 * \n
2604 * For example, if the global dual bound is 50 and the primal bound is 60, SEPA_MAXBOUNDDIST = 0.25 means that separation
2605 * is only applied if the current node's dual bound is in the first quarter of the interval [50,60], i.e., if it is less
2606 * than or equal to 52.5.
2607 * \n
2608 * In particular, the values 0.0 and 1.0 mean that separation is applied at the current best node only or at all
2609 * nodes, respectively. Since separation seems to be most important to apply at nodes that define to the global
2610 * dual bound, 0.0 is probably a good choice for SEPA_MAXBOUNDDIST.
2611 * Note that separators with a frequency of SEPA_FREQ = 0 are only applied at the root node.
2612 * Obviously, at the root node the local dual bound is equal to the global dual bound and thus, the separator is called
2613 * for any value of SEPA_MAXBOUNDDIST.
2614 *
2615 * \par SEPA_USESSUBSCIP: Does the separator use a secondary SCIP instance?
2616 * Some heuristics and separators solve MIPs or SAT problems and use a secondary SCIP instance. Examples are
2617 * Large Neighborhood Search heuristics such as RINS and Local Branching or the CGMIP separator. To avoid recursion,
2618 * these plugins usually deactivate all other plugins that solve MIPs. If a separator uses a secondary SCIP instance,
2619 * this parameter has to be TRUE and it is recommended to call SCIPsetSubscipsOff() for the secondary SCIP instance.
2620 *
2621 * \par SEPA_DELAY: the default for whether the separation method should be delayed, if other separators or constraint handlers found cuts.
2622 * If the separator's separation method is marked to be delayed, it is only executed after no other separator
2623 * or constraint handler found a cut during the price-and-cut loop.
2624 * If the separation method of the separator is very expensive, you may want to mark it to be delayed until all cheap
2625 * separation methods have been executed.
2626 *
2627 * @section SEPA_DATA Separator Data
2628 *
2629 * Below the header "Data structures" you can find a struct which is called "struct SCIP_SepaData".
2630 * In this data structure, you can store the data of your separator. For example, you should store the adjustable
2631 * parameters of the separator in this data structure. In a separator, user parameters for the maximal number of
2632 * separation rounds per node and for the maximal number of cuts separated per separation round might be useful.
2633 * If you are using C++, you can add separator data as usual as object variables to your class.
2634 * \n
2635 * Defining separator data is optional. You can leave the struct empty.
2636 *
2637 * @section SEPA_INTERFACE Interface Methods
2638 *
2639 * At the bottom of "sepa_myseparator.c", you can find the interface method SCIPincludeSepaMyseparator(),
2640 * which also appears in "sepa_myseparator.h"
2641 * SCIPincludeSepaMyseparator() is called by the user, if (s)he wants to include the separator,
2642 * i.e., if (s)he wants to use the separator in his/her application.
2643 *
2644 * This method only has to be adjusted slightly.
2645 * It is responsible for notifying SCIP of the presence of the separator. For this, you can either call SCIPincludeSepa(),
2646 * or SCIPincludeSepaBasic() since SCIP version 3.0. In the latter variant, \ref SEPA_ADDITIONALCALLBACKS "additional callbacks"
2647 * must be added via setter functions as, e.g., SCIPsetSepaCopy(). We recommend this latter variant because
2648 * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2649 * variant must be manually adjusted with every SCIP release containing new callbacks for separators in order to compile.
2650 *
2651 * If you are using separator data, you have to allocate the memory
2652 * for the data at this point. You can do this by calling:
2784 * Propagators are used to tighten the domains of the variables. Like for cutting planes, there are two different types
2785 * of domain propagations. Constraint based (primal) domain propagation algorithms are part of the corresponding
2786 * constraint handlers, see \ref CONSPROP. In contrast, domain propagators usually provide dual propagations, i.e.,
2787 * propagations that can be applied using the objective function and the current best known primal solution. This
2788 * section deals with such propagators.
2789 *
2790 * A complete list of all propagators contained in this release can be found \ref PROPAGATORS "here".
2791 *
2792 * We now explain how users can add their own propagators. Take the pseudo objective function propagator
2793 * (src/scip/prop_pseudoobj.c) as an example. As all other default plugins, it is written in C. C++ users can easily
2794 * adapt the code by using the scip::ObjProp wrapper base class and implement the @c scip_...() virtual methods instead
2795 * of the @c SCIP_DECL_PROP... callback methods.
2796 *
2797 * Additional documentation for the callback methods of a propagator can be found in the file type_prop.h.
2798 *
2799 * Here is what you have to do to implement a propagator:
2800 * -# Copy the template files src/scip/prop_xyz.c and src/scip/prop_xyz.h into files named "prop_mypropagator.c"
2801 * and "prop_mypropagator.h".
2802 * \n
2803 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
2804 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
2805 * -# Use `SCIPincludePropMypropagator()` in order to include the propagator into your SCIP instance,
2806 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
2807 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
2808 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypropagator".
2809 * -# Adjust the properties of the propagator (see \ref PROP_PROPERTIES).
2810 * -# Define the propagator data (see \ref PROP_DATA). This is optional.
2811 * -# Implement the interface methods (see \ref PROP_INTERFACE).
2812 * -# Implement the fundamental callback methods (see \ref PROP_FUNDAMENTALCALLBACKS).
2813 * -# Implement the additional callback methods (see \ref PROP_ADDITIONALCALLBACKS). This is optional.
2814 *
2815 * @section PROP_PROPERTIES Properties of a Propagator
2816 *
2817 * At the top of the new file "prop_mypropagator.c" you can find the propagator properties. These are given as compiler
2818 * defines. The presolving-related properties are optional,
2819 * they only have to be defined if the propagator supports presolving routines.
2820 * In the C++ wrapper class, you have to provide the propagator properties by calling the constructor of the
2821 * abstract base class scip::ObjProp from within your constructor. The properties you have the following meaning:
2822 *
2823 * @subsection PROP_FUNDAMENTALPROPERTIES Fundamental properties of a propagator
2824 *
2825 * \par PROP_NAME: the name of the propagator.
2826 * This name is used in the interactive shell to address the propagator. Additionally, if you are searching for a
2827 * propagator with SCIPfindProp(), this name is searched for. Names have to be unique: no two propagators may have the
2828 * same name.
2829 *
2830 * \par PROP_DESC: the description of the propagator.
2831 * This string is printed as a description of the propagator in the interactive shell.
2832 *
2833 * \par PROP_PRIORITY: the priority of the propagator.
2834 * In each propagation round, the propagators and propagation methods of the constraint handlers are called in a
2835 * predefined order, which is given by the priorities of the propagators and the check priorities of the constraint
2836 * handlers. First, the propagators with non-negative priority are called in order of decreasing priority. Next, the
2837 * propagation methods of the different constraint handlers are called in order of decreasing check priority. Finally,
2838 * the propagators with negative priority are called in order of decreasing priority. \n The priority of the
2839 * propagators should be set according to the complexity of the propagation algorithm and the impact of the domain
2840 * propagations: propagators providing fast algorithms that usually have a high impact (i.e., tighten many bounds)
2841 * should have a high priority.
2842 *
2843 * \par PROP_FREQ: the default frequency for propagating domains.
2844 * The frequency defines the depth levels at which the propagation method \ref PROPEXEC is called. For example, a
2845 * frequency of 7 means, that the propagation callback is executed for subproblems that are in depth 0, 7, 14, ... of
2846 * the branching tree. A frequency of 0 means that propagation is only applied in preprocessing and at the root node. A
2847 * frequency of -1 disables the propagator.
2848 * \n
2849 * The frequency can be adjusted by the user. This property of the propagator only defines the default value of the
2850 * frequency.\n
2851 * <b>Note:</b> If you want to have a more flexible control of when to execute the propagation algorithm, you have to
2852 * assign a frequency of 1 and implement a check at the beginning of your propagation algorithm whether you really want
2853 * to execute the domain propagation or not. If you do not want to execute it, set the result code to SCIP_DIDNOTRUN.
2854 *
2855 * \par PROP_DELAY: the default for whether the propagation method should be delayed, if other propagators or constraint handlers found domain reductions.
2856 * If the propagator's propagation method is marked to be delayed, it is only executed after no other propagator or
2857 * constraint handler found a domain reduction in the current iteration of the domain propagation loop. If the
2858 * propagation method of the propagator is very expensive, you may want to mark it to be delayed until all cheap
2859 * propagation methods have been executed.
2860 *
2861 * \par PROP_TIMING: the timing mask of the propagator.
2862 * SCIP calls the domain propagation routines at different places in the node processing loop.
2863 * This property indicates at which places the propagator is called.
2864 * Possible values are defined in type_timing.h and can be concatenated, e.g., as in SCIP_PROPTIMING_ALWAYS.
3068 * Branching rules are used to split the problem at the current node into smaller subproblems. Branching rules can be called at three
3069 * different occasions, which is why they have three different execution methods (see \ref
3070 * BRANCHRULE_ADDITIONALCALLBACKS). Branching is performed if:
3071 * - the LP solution of the current problem is fractional. In this case, the integrality constraint handler calls the
3072 * \ref BRANCHEXECLP methods of the branching rules.
3073 * - the list of external branching candidates is not empty. This will only be the case if branching candidates were added
3074 * by a user's \ref RELAX "relaxation handler" or \ref CONS "constraint handler" plugin, calling SCIPaddExternBranchCand().
3075 * These branching candidates should be processed by the \ref BRANCHEXECEXT method.
3076 * - if an integral solution violates one or more constraints and this infeasibility could not be resolved in the callback methods
3077 * \ref CONSENFOLP and \ref CONSENFOPS of the corresponding constraint handlers. In this case, the \ref BRANCHEXECPS method will be called. This is the
3078 * standard case, if you use SCIP as a pure CP or SAT solver. If the LP or any other type of relaxation is used, then
3079 * branching on pseudo solutions works as a last resort.
3080 *
3081 * The idea of branching rules is to take a global view on the problem. In contrast, branching paradigms which are
3082 * specific to one type of constraint are best implemented within the enforcement callbacks of your constraint handler.
3083 * See, e.g., the constraint specific branching rules provided by the constraint handlers for special ordered sets
3084 * (src/scip/cons_sos{1,2}.c)).
3085 * \n
3086 * All branching rules that come with the default distribution of SCIP create two subproblems by splitting a single
3087 * variable's domain. It is, however, fully supported to implement much more general branching schemes, for example by
3088 * creating more than two subproblems, or by adding additional constraints to the subproblems instead of tightening the
3089 * domains of the variables.
3090 * \n
3091 * A complete list of all branching rules contained in this release can be found \ref BRANCHINGRULES "here".
3092 * However, note that constraint handlers can implement their own branching when enforcing constraints.
3093 * In particular the handler for nonlinear constraints currently does not use the branching plugins for spatial branching
3094 * by default. Its behavior can be adjusted with the parameters in category constraints/nonlinear/branching.
3095 *
3096 * We now explain how users can add their own branching rules. Take the most infeasible LP branching rule
3097 * (src/scip/branch_mostinf.c) as an example. As all other default plugins, it is written in C. C++ users can easily
3098 * adapt the code by using the scip::ObjBranchrule wrapper base class and implement the scip_...() virtual methods instead of
3099 * the SCIP_DECL_BRANCH... callback methods.
3100 *
3101 * Additional documentation for the callback methods of a branching rule can be found in the file type_branch.h.
3102 *
3103 * Here is what you have to do to implement a branching rule:
3104 * -# Copy the template files src/scip/branch_xyz.c and src/scip/branch_xyz.h into files named
3105 * "branch_mybranchingrule.c" and "branch_mybranchingrule.h".
3106 * \n
3107 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
3108 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
3109 * -# Use `SCIPincludeBranchruleMybranchingrule()` in order to include the branching rule into your SCIP instance,
3110 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
3111 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
3112 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mybranchingrule".
3113 * -# Adjust the properties of the branching rule (see \ref BRANCHRULE_PROPERTIES).
3114 * -# Define the branching rule data (see \ref BRANCHRULE_DATA). This is optional.
3115 * -# Implement the interface methods (see \ref BRANCHRULE_INTERFACE).
3116 * -# Implement the fundamental callback methods (see \ref BRANCHRULE_FUNDAMENTALCALLBACKS).
3117 * -# Implement the additional callback methods (see \ref BRANCHRULE_ADDITIONALCALLBACKS). This is optional.
3118 *
3119 *
3120 * @section BRANCHRULE_PROPERTIES Properties of a Branching Rule
3121 *
3122 * At the top of the new file "branch_mybranchingrule.c" you can find the branching rule properties.
3123 * These are given as compiler defines.
3124 * In the C++ wrapper class, you have to provide the branching rule properties by calling the constructor
3125 * of the abstract base class scip::ObjBranchrule from within your constructor.
3126 * The properties you have to set have the following meaning:
3127 *
3128 * \par BRANCHRULE_NAME: the name of the branching rule.
3129 * This name is used in the interactive shell to address the branching rule.
3130 * Additionally, if you are searching for a branching rule with SCIPfindBranchrule(), this name is looked up.
3131 * Names have to be unique: no two branching rules may have the same name.
3132 *
3133 * \par BRANCHRULE_DESC: the description of the branching rule.
3134 * This string is printed as a description of the branching rule in the interactive shell.
3135 *
3136 * \par BRANCHRULE_PRIORITY: the default value for the priority of the branching rule.
3137 * In the subproblem processing, the branching rules are called in decreasing order of their priority until
3138 * one succeeded to branch. Since most branching rules are able to generate a branching in all situations,
3139 * only the rule of highest priority is used. In combination with the BRANCHRULE_MAXDEPTH and
3140 * BRANCHRULE_MAXBOUNDDIST settings, however, interesting strategies can be easily employed. For example,
3141 * the user can set the priority of the "full strong branching" strategy to the highest value and assign the
3142 * second highest value to the "reliable pseudo cost" rule. If (s)he also sets the maximal depth for the
3143 * "full strong branching" to 5, in the top 5 depth levels of the search tree the "full strong branching" is
3144 * applied, while in the deeper levels "reliable pseudo cost branching" is used.
3145 * \n
3146 * Note that the BRANCHRULE_PRIORITY property only specifies the default value of the priority. The user can
3147 * change this value arbitrarily.
3148 *
3149 * \par BRANCHRULE_MAXDEPTH: the default value for the maximal depth level of the branching rule.
3150 * This parameter denotes the maximal depth level in the branch-and-bound tree up to which the branching method of the
3151 * branching rule will be applied. Use -1 for no limit.
3152 * \n
3153 * Note that this property only specifies the default value. The user can change this value arbitrarily.
3154 *
3155 * \par BRANCHRULE_MAXBOUNDDIST: the default value for the maximal relative distance from current node's dual bound to primal bound compared to best node's dual bound for applying branching.
3156 * At the current branch-and-bound node, the relative distance from its dual bound (local dual bound)
3157 * to the primal bound compared to the best node's dual bound (global dual bound) is considered. The branching method of
3158 * the branching rule will only be applied at the node if this relative distance does not exceed BRANCHRULE_MAXBOUNDDIST.
3159 * \n
3160 * For example, if the global dual bound is 50 and the primal bound is 60, BRANCHRULE_MAXBOUNDDIST = 0.25 means that
3161 * branching is only applied if the current node's dual bound is in the first quarter of the interval [50,60], i.e., if it
3162 * is less than or equal to 52.5. In particular, the values 0.0 and 1.0 mean that the branching rule is applied at the
3163 * current best node only or at all nodes, respectively.
3164 * \n
3165 * Note that the BRANCHRULE_MAXBOUNDDIST property only specifies the default value of the maximal bound distance.
3166 * The user can change this value arbitrarily.
3167 *
3168 *
3169 * @section BRANCHRULE_DATA Branching Rule Data
3170 *
3171 * Below the header "Data structures" you can find a struct which is called "struct SCIP_BranchruleData".
3172 * In this data structure, you can store the data of your branching rule. For example, you should store the adjustable
3173 * parameters of the branching rule in this data structure.
3174 * If you are using C++, you can add branching rule data as usual as object variables to your class.
3175 * \n
3176 * Defining branching rule data is optional. You can leave the struct empty.
4292 * If this callback is not implemented, the expression is assumed to be indefinite.
4293 *
4294 * @subsection EXPRMONOTONICITY
4295 *
4296 * This callback is called when an expression is checked for its monotonicity with respect to a given child.
4297 * It is given the index of the child and shall return whether the expression is monotonically increasing or decreasing with respect to this child,
4298 * that is, when assuming that all other children are fixed.
4299 * Bounds on the children can be taken into account.
4300 * These can be evaluated and obtained via SCIPevalExprActivity() and SCIPexprGetActivity().
4301 *
4302 * The implementation in the absolute value expression handler serves as an example:
4389 * If this callback is not implemented, routines (in particular primal heuristics) that rely on solving NLPs cannot be used, as they currently rely on using forward differentiation for gradient computations.
4390 *
4391 * @subsection EXPRBWFWDIFF
4392 *
4393 * This callback is called when the Hessian of a function that is represented by an expression is computed.
4394 *
4395 * The method computes the total derivative, w.r.t. its children, of the partial derivative of expr w.r.t. childidx.
4396 * Equivalently, it computes the partial derivative w.r.t. childidx of the total derivative.
4397 *
4398 * The expression should be interpreted as an operator \f$ f(c_1, \ldots, c_n) \f$, where \f$ c_1, \ldots, c_n \f$ are the children,
4417 * If this callback is not implemented, there is currently no particular performance impact.
4418 * In a future version, not implementing this callback would mean that Hessians are not available for NLP solvers, in which case they may have to work with approximations.
4419 *
4420 * @subsection EXPRINTEVAL
4421 *
4422 * This callback is called when bounds on an expression need to be computed.
4423 * It shall compute an (as tight as possible) overestimate on the range that the expression values take w.r.t. bounds (given as \ref SCIP_INTERVAL) for the children.
4424 * The latter can be accessed via SCIPexprGetActivity().
4425 *
4426 * Often, interval evaluation is implemented analogous to evaluation with numbers.
4430 * If this callback is not implemented, the performance of domain propagation for nonlinear constraints and other routines that rely on bounds of expressions will be impacted severely.
4431 *
4432 * @subsection EXPRESTIMATE
4433 *
4434 * While \ref EXPRINTEVAL computes constant under- and overestimators,
4435 * this callback is called when linear under- or overestimators need to be computed.
4436 * The estimator shall be as tight as possible at a given point and must be valid w.r.t. given (local) bounds.
4437 * If the value of the estimator in the reference point is smaller (larger) than a given targetvalue
4438 * when underestimating (overestimating), then no estimator needs to be computed.
4439 * Note, that targetvalue can be infinite if any estimator will be accepted.
4440 *
4441 * The callback shall also indicate whether the estimator is also valid w.r.t. given global bounds and for which
4442 * child a reduction in the local bounds (usually by branching) would improve the estimator.
4443 *
4444 * For the absolute-value expression, the under- and overestimators are computed as follows:
4447 * If this callback is not implemented, updating the linear relaxation for nonlinear constraints that use this expression will not be possible, which has a severe impact on performance.
4448 *
4449 * @subsection EXPRINITESTIMATES
4450 *
4451 * This callback is similar to \ref EXPRESTIMATE, but is not given a reference point.
4452 * It can also return several (up to \ref SCIP_EXPR_MAXINITESTIMATES many) estimators.
4453 * A usecase for this callback is the construction of an initial linear relaxation of nonlinear constraints.
4454 *
4455 * For the absolute-value expression, the following initial under- and overestimators are computed:
4475 * See also SCIPsimplifyExpr() for more information on implemented simplification rules.
4476 *
4477 * If this callback is not implemented, reducing the problem size when variables are fixed may not be possible, which can have an impact on performance.
4478 * (Also bugs may show up as this situation is untested.)
4479 *
4480 * @subsection EXPRREVERSEPROP
4481 *
4482 * This callback is called when given bounds on an expression shall be propagated over the children of an expression.
4483 * Already existing bounds on the children (see \ref EXPRINTEVAL) shall be used.
4484 * That is, the method shall compute an interval overestimate on
4503 * Nonlinear handlers define the extended formulations of nonlinear constraints and provide domain propagation and separation routines on this extended formulation.
4504 * In difference to \ref EXPRHDLR "expression handlers", they do not define a function, but instead identify a
4505 * structure in an existing expression and provide bound tightening and separation on this structure similar to \ref EXPRINTEVAL, \ref EXPRREVERSEPROP, \ref EXPRINITESTIMATES, and \ref EXPRESTIMATE.
4506 * The structure typically consists of a composition of expressions.
4507 *
4508 * Nonlinear handlers are a new plugin type in SCIP and may still have some rough edges.
4509 * They resemble constraint handlers in some sense, but are specific to the handling of nonlinear constraints.
4510 * We suggest to read section "New Handler for Nonlinear Constraints" in the SCIP 8.0 release report (2021)
4511 * to understand the role and use of nonlinear handlers before attempting to implement one.
4512 *
4513 * A complete list of all nonlinear handlers contained in this release can be found \ref NLHDLRS "here".
4514 * In difference to many other plugins in SCIP, nonlinear handlers are not handled by the SCIP core but by the constraint handler for nonlinear constraints.
4515 *
4516 * Here is what you have to do to implement a nonlinear handler:
4517 * -# Copy the template files `src/scip/nlhdlr_xyz.c` and `src/scip/nlhdlr_xyz.h` into files `nlhdlr_mystruct.c` and `nlhdlr_mystruct.h`, respectively. \n
4518 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
4519 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
4520 * -# Use `SCIPincludeNlhdlrMystruct()` in order to include the nonlinear handler into your SCIP instance, e.g., in the main file of your project. \n
4521 If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
4522 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mystruct".
4523 * -# Adjust the properties of the nonlinear handler (see \ref NLHDLR_PROPERTIES).
4524 * -# Define the nonlinear handler data and nonlinear handler expression data (see \ref NLHDLR_DATA). This is optional.
4525 * -# Implement the interface methods (see \ref NLHDLR_INTERFACE).
4526 * -# Implement the fundamental callback methods (see \ref NLHDLR_FUNDAMENTALCALLBACKS).
4527 * -# Implement the additional callback methods (see \ref NLHDLR_ADDITIONALCALLBACKS), where necessary.
4528 *
4529 * Additional documentation for the callback methods of a nonlinear handler, in particular for the input parameters,
4530 * can be found in the file \ref type_nlhdlr.h.
4531 *
4532 * @section NLHDLR_PROPERTIES Properties of a Nonlinear Handler
4533 *
4534 * At the top of the new file `nlhdlr_mystruct.c`, you can find the nonlinear handler properties.
4535 * These are given as compiler defines.
4536 * The properties you have to set have the following meaning:
4537 *
4538 * \par NLHDLR_NAME: the name of the nonlinear handler.
4539 * This name is used in the interactive shell to address the nonlinear handler.
4540 * Additionally, if you are searching for a nonlinear handler with SCIPfindNlhdlrNonlinear(), this name is looked up.
4541 * Names have to be unique: no two nonlinear handlers may have the same name.
4542 *
4543 * \par NLHDLR_DESC: the description of the nonlinear handler.
4544 * This string is printed as a description of the nonlinear handler in the interactive shell.
4545 *
4546 * \par NLHDLR_DETECTPRIORITY: the priority of the nonlinear handler when detecting structure.
4547 * This priority decides when the \ref NLHDLRDETECT callback of the nonlinear handler is called, relative to other nonlinear handlers, on an expression.
4548 * Typically, the priority should be strictly positive.
4549 * This is because the nonlinear handler "default" (having detection priority 0) will not become active on expressions that are already handled by other nonlinear handlers.
4550 *
4551 * \par NLHDLR_ENFOPRIORITY: the priority of the nonlinear handler when enforcing constraints in the extended formulations.
4552 * This priority decides when the callbacks that help on domain propagation and separation are called for an expression for which the nonlinear handler detected a structure.
4553 * A high priority means that the nonlinear handler will be called before others.
4554 * The nonlinear handler "default" has enforcement priority 0.
4555 *
4556 * @section NLHDLR_DATA Nonlinear Handler Data and Nonlinear Handler Expression Data
4557 *
4558 * Below the header "Data structures" you can find structs called `struct SCIP_NlhdlrData` and `struct SCIP_NlhdlrExprData`.
4559 * In this first data structure, you can store the data of your nonlinear handler.
4560 * For example, you should store the adjustable parameters of the nonlinear handler in this data structure.
4561 * In the second data structure, you can store data that is unique to an expression for which the nonlinear handler detected a structure.
4562 * For example, the nonlinear handler for quotients stores a representation of a detected quotient in this data structure.
4563 * \n
4564 * Defining nonlinear handler data and nonlinear handler expression data is optional. You can leave these structs empty.
4586 * @section NLHDLR_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Nonlinear Handler
4587 *
4588 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
4589 * an operational algorithm.
4590 * They are passed to SCIP when the nonlinear handler is created and included in SCIP via SCIPincludeNlhdlrNonlinear(),
4591 * see @ref NLHDLR_INTERFACE.
4592 *
4593 * Nonlinear handlers have two fundamental callbacks that need to be implemented.
4594 * Additional documentation for the callback methods, in particular to their input parameters,
4595 * can be found in \ref type_nlhdlr.h.
4596 *
4597 * @subsection NLHDLRDETECT
4598 *
4599 * This callback is called by the handler for nonlinear constraints when extended formulations are constructed.
4600 * The result of this callback determines the extended formulation.
4601 *
4602 * The nonlinear handler shall analyze the given expression (`expr`) and decide whether it wants to contribute
4603 * in enforcing the relation between bounds or an auxiliary variable (`auxvar`) associated with this expression and
4604 * its descendants (e.g., children) via linear under- or overestimation, cut generation, and/or activity computation and propagation.
4605 * For linear under- or overestimation and cut generation, an auxiliary variable can be assumed to
4606 * be associated with the expression and auxiliary variables may be requested for descendant expressions.
4607 *
4608 * We distinguish the following enforcement methods:
4609 * - \ref SCIP_NLHDLR_METHOD_SEPABELOW : linear underestimation of `expr` or cut generation for the relation `expr` ≤ `auxvar` (denoted as "below")
4610 * - \ref SCIP_NLHDLR_METHOD_SEPAABOVE : linear overestimation of `expr` or cut generation for the relation `expr` ≥ `auxvar` (denoted as "above")
4613 * On input, parameter `enforcing` indicates for any of these methods, whether
4614 * - it is not necessary to have such a method, e.g., because no `auxvar` will exist for `expr`, or no one uses or sets activities of this expression,
4615 * or because analysis of the expression has shown that a relation like `expr` ≥ `auxvar` is not necessary to be satisfied,
4616 * - or there already exists a nonlinear handler that will provide this method in an "enforcement" sense, that is,
4617 * it believes that no one else could provide this method in a stronger sense. (This is mainly used by the nonlinear handler "default" to check whether
4618 * it should still reach out to the expression handler or whether it would be dominated by some nonlinear handler.)
4619 *
4620 * The DETECT callback shall augment the `enforcing` bitmask by setting the enforcement methods it wants to provide in an "enforcement" sense.
4621 *
4622 * Additionally, the `participating` bitmask shall be set if the nonlinear handler wants to be called on this expression at all.
4623 * Here, it shall set all methods that it wants to provide, which are those set in `enforcing`, but additionally those where it wants
4624 * to participate but leave enforcement to another nonlinear handler.
4625 * This can be useful for nonlinear handlers that do not implement a complete enforcement, e.g., a handler that only contributes
4626 * cutting planes in some situations only.
4627 *
4628 * A nonlinear handler will be called only for those callbacks that it mentioned in `participating`, which is
4629 * - \ref NLHDLRENFO and/or \ref NLHDLRESTIMATE will be called with `overestimate==FALSE` if \ref SCIP_NLHDLR_METHOD_SEPABELOW has been set
4630 * - \ref NLHDLRENFO and/or \ref NLHDLRESTIMATE will be called with `overestimate==TRUE` if \ref SCIP_NLHDLR_METHOD_SEPAABOVE has been set
4631 * - \ref NLHDLRINTEVAL and/or \ref NLHDLRREVERSEPROP will be called if \ref SCIP_NLHDLR_METHOD_ACTIVITY has been set
4632 *
4633 * If \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE has been set, then at least one of the
4634 * callbacks \ref NLHDLRENFO and \ref NLHDLRESTIMATE needs to be implemented.
4635 * Also \ref NLHDLREVALAUX will be called in this case.
4636 * If \ref SCIP_NLHDLR_METHOD_ACTIVITY has been set, then at least one of \ref NLHDLRINTEVAL and \ref NLHDLRREVERSEPROP needs to be implemented.
4637 * If the nonlinear handler chooses not to participate, then it must not set `nlhdlrexprdata` and can leave `participating` at its
4638 * initial value (\ref SCIP_NLHDLR_METHOD_NONE).
4639 *
4640 * Additionally, a nonlinear handler that decides to participate in any of the enforcement methods must call
4641 * @ref SCIPregisterExprUsageNonlinear() for every subexpression that it will use and indicate whether
4642 * - it will use an auxiliary variable in \ref NLHDLRENFO or \ref NLHDLRESTIMATE,
4643 * - it will use activity for some subexpressions when computing estimators or cuts, and
4644 * - it will use activity for some subexpressions when in \ref NLHDLRINTEVAL or \ref NLHDLRREVERSEPROP.
4645 *
4646 * Note that auxiliary variables do not exist in subexpressions during DETECT and are not created by a call to @ref SCIPregisterExprUsageNonlinear().
4647 * They will be available when the \ref NLHDLRINITSEPA callback is called.
4648 *
4649 * For an example, see the implementation of the DETECT callback for the nonlinear handler for quotients (src/scip/nlhdlr_quotient.c).
4650 *
4651 * @subsection NLHDLREVALAUX
4652 *
4653 * This callback is called by the constraint handler for nonlinear constraints when the violation of constraints in the extended formulation
4654 * (`expr` ≤/≥ `auxvar`) needs to be evaluated.
4655 * During constraint enforcement, this violation value is used to decide whether estimation and separation callbacks should be called.
4656 *
4657 * The method shall evaluate the expression w.r.t. the auxiliary variables that were introduced by the nonlinear handler (if any).
4658 * It can be assumed that the expression itself has been evaluated in the given sol.
4659 *
4660 * For an example, see the evaluation for the quotient nonlinear handler:
4663 * @section NLHDLR_ADDITIONALCALLBACKS Additional Callback Methods of a Nonlinear Handler
4664 *
4665 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
4666 * implemented for most applications, they can be used, for example, to initialize and free private data.
4667 * Additional callbacks can be passed via specific
4668 * <b>setter functions</b> after a call of SCIPincludeNlhdlrNonlinear(), see also @ref NLHDLR_INTERFACE.
4669 *
4670 * @subsection NLHDLRCOPYHDLR
4671 *
4672 * This callback is called when doing a copy of the constraint handler for nonlinear constraints.
4673 * It shall include the nonlinear handler into the copy of the constraint handler.
4674 *
4675 * @subsection NLHDLRFREEHDLRDATA
4676 *
4677 * If you are using nonlinear handler data (see \ref NLHDLR_DATA and \ref NLHDLR_INTERFACE), you have to implement this method
4678 * in order to free the nonlinear handler data.
4679 *
4680 * @subsection NLHDLRFREEEXPRDATA
4681 *
4682 * If you are using nonlinear handler expression data (see \ref NLHDLR_DATA and \ref NLHDLRDETECT), you have to implement this method
4683 * in order to free the nonlinear handler expression data.
4684 * This method is called when an extended formulation is freed.
4685 *
4686 * @subsection NLHDLRINIT
4687 *
4688 * This callback is called when the constraint handler for nonlinear constraints is initialized, that is, after the problem was transformed.
4689 * The nonlinear handler can use this callback to initialize or reset some data for the upcoming solve.
4690 *
4691 * @subsection NLHDLREXIT
4692 *
4693 * This callback is called when the constraint handler for nonlinear constraints is deinitialized, that is, before the transformed problem is freed.
4694 * The nonlinear handler can use this callback to free some data that was used for the previous solve only.
4695 *
4696 * @subsection NLHDLRINTEVAL
4697 *
4698 * This callback is called when bounds on a given expression shall be computed.
4699 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_ACTIVITY in \ref NLHDLRDETECT.
4700 * The method is given the currently available bounds to the expression and can return possibly tighter bounds.
4701 *
4702 * For a univariate quotient ((ax+b)/(cx+d)), the interval evaluation is implemented as follows:
4707 * This callback is called when bounds on a given expression shall be propagated to its successors.
4708 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_ACTIVITY in \ref NLHDLRDETECT.
4709 * The tighter intervals should be passed to the corresponding expression via SCIPtightenExprIntervalNonlinear().
4710 *
4711 * For a univariate quotient ((ax+b)/(cx+d)), reverse propagation is implemented as follows:
4716 * This callback is called when the constraint handler for nonlinear constraints initializes the LP relaxation (@ref CONSINITLP).
4717 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE in \ref NLHDLRDETECT.
4718 * The method shall initialize the separation data of the nonlinear handler, if any, and add initial cuts to the LP relaxation.
4719 * It can assume that auxiliary variables are available for expressions for which auxiliary variables were requested via SCIPregisterExprUsageNonlinear() in \ref NLHDLRDETECT.
4720 *
4721 * @subsection NLHDLREXITSEPA
4722 *
4723 * This callback is called when the solving process is finished and the branch and bound process data is freed (@ref CONSEXITSOL).
4724 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE in \ref NLHDLRDETECT and \ref NLHDLRINITSEPA was called.
4725 * The method shall deinitialize the separation data of the nonlinear handler, if any.
4726 *
4727 * @subsection NLHDLRENFO
4728 *
4729 * This callback is called when the constraint handler requires that the relation between the given expression and its auxiliary variable
4730 * (`expr` ≤ `auxvar` or `expr` ≥ `auxvar`) is violated by a given solution and this solution needs to be separated.
4731 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE in \ref NLHDLRDETECT.
4732 *
4733 * The nonlinear handler can enforce `expr` ≤/≥ `auxvar` by
4734 * - separation, i.e., finding an affine hyperplane (a cut) that separates the given point, or
4735 * - bound tightening, i.e., changing bounds on a variable so that the given point is outside the updated domain, or
4736 * - adding branching scores to potentially split the current problem into two subproblems.
4737 *
4738 * If parameter `inenforcement` is FALSE, then only the first option (separation) is allowed.
4739 *
4740 * If the nonlinear handler always separates by computing a linear under- or overestimator of `expr`,
4741 * then it is usually easier to implement the \ref NLHDLRESTIMATE callback instead.
4742 *
4743 * Note, that the nonlinear handler may also choose to separate for a relaxation of the mentioned sets,
4744 * e.g., `expr` ≤ upperbound(`auxvar`) or `expr` ≥ lowerbound(`auxvar`).
4745 * This is especially useful in situations where `expr` is the root expression of a constraint
4746 * and it is sufficient to satisfy `lhs` ≤ `expr` ≤ `rhs`.
4747 * The constraint handler ensures that `lhs` ≤ lowerbound(`auxvar`) and upperbound(`auxvar`) ≤ `rhs`.
4748 *
4749 * The constraint handler may call this callback first with `allowweakcuts` = FALSE and repeat later with
4750 * `allowweakcuts` = TRUE, if it didn't succeed to enforce a solution without using weak cuts.
4751 * If in enforcement and the nonlinear handler cannot enforce by separation or bound tightening, it should register
4752 * branching scores for those expressions where branching may help to compute tighter cuts in children.
4753 *
4754 * The nonlinear handler must set `result` to \ref SCIP_SEPARATED if it added a cut,
4755 * to \ref SCIP_REDUCEDDOM if it added a bound change, and
4756 * to \ref SCIP_BRANCHED if it added branching scores.
4757 * Otherwise, it may set result to \ref SCIP_DIDNOTRUN or \ref SCIP_DIDNOTFIND.
4758 *
4759 * @subsection NLHDLRESTIMATE
4760 *
4761 * This callback is called when the constraint handler requires that the relaxation between the given expression and its auxiliary variable
4762 * (`expr` ≤ `auxvar` or `expr` ≥ `auxvar`) is violated by a given solution and this solution needs to be separated.
4763 * It is called for expressions for which the nonlinear handler registered to participate in \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE in \ref NLHDLRDETECT.
4764 * This method is a simpler alternative to \ref NLHDLRENFO and is called if \ref NLHDLRENFO is not implemented or does not succeed.
4765 *
4766 * The method shall compute one or several linear under- or overestimator of `expr` that are as tight as possible at a given point.
4767 * If the value of the estimator in the solution is smaller (larger) than a given targetvalue
4768 * when underestimating (overestimating), then no estimator needs to be computed.
4769 * Note, that targetvalue can be infinite if any estimator will be accepted.
4770 * If successful, it shall store the estimators in the given `rowpreps` data structure and set the
4771 * `rowprep->local` flag accordingly (SCIProwprepSetLocal()).
4772 * The sidetype of a rowprep must be set to \ref SCIP_SIDETYPE_LEFT if overestimating and
4773 * \ref SCIP_SIDETYPE_RIGHT if underestimating.
4774 *
4775 * The callback may also be required to indicate for which expression a reduction in the local bounds (usually by branching) would improve the estimator.
4776 * This is done by a call to SCIPaddExprsViolScoreNonlinear().
4777 *
4778 * For the quotient nonlinear handler, the estimators are computed as follows:
4783 * This callback is called by the constraint handler when it has caught a solution event from SCIP and option constraints/nonlinear/linearizeheursol has been enabled.
4784 * The constraint handler then calls the nonlinear handlers for all expressions they currently handle.
4785 * The nonlinear handler may use this opportunity to add a cut that supports its nonlinear function in the given solution to the cutpool.
4786 * For convex functions, this may help to accellerate proving optimality for a solution found by a NLP solver.
5015 * You also have to initialize the fields in struct SCIP_RelaxData afterwards.
5016 *
5017 * You may also add user parameters for your relaxation handler, see the method SCIPincludeConshdlrKnapsack() in
5018 * the \ref cons_knapsack.h "knapsack constraint handler" for an example of how to add user parameters.
5019 *
5020 *
5021 * @section RELAX_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Relaxation Handler
5022 *
5023 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
5024 * an operational algorithm.
5025 * They are passed together with the relaxation handler itself to SCIP using SCIPincludeRelax() or SCIPincludeRelaxBasic(),
5026 * see @ref RELAX_INTERFACE.
5027 *
5028 *
5029 * Relaxation handler plugins have only one fundamental callback method, namely the \ref RELAXEXEC method.
5030 * This method has to be implemented for every relaxation handler; the other callback methods are optional.
5031 * In the C++ wrapper class scip::ObjRelax, the scip_exec() method (which corresponds to the \ref RELAXEXEC callback) is a virtual
5032 * abstract member function.
5033 * You have to implement it in order to be able to construct an object of your relaxation handler class.
5034 *
5035 * Additional documentation for the callback methods can be found in type_relax.h.
5036 *
5037 * @subsection RELAXEXEC
5038 * The RELAXEXEC is called in each relaxation solving round. It should solve the current
5039 * subproblem's relaxation.
5040 *
5041 * Note that, like the LP relaxation, the relaxation handler should only operate on variables for which the corresponding
5042 * column exists in the transformed problem. Typical methods called by a relaxation handler are SCIPconstructLP() and SCIPflushLP() to
5043 * make sure that the LP of the current node is constructed and its data can be accessed via calls to SCIPgetLPRowsData()
5044 * and SCIPgetLPColsData(), and SCIPseparateSol() to call the cutting plane separators for a given primal solution.
5045 *
5046 * The lowerbound computed by the relaxation should be returned in the lowerbound pointer. If the relaxation improves on the best
5047 * relaxation already computed (either <code>SCIPisRelaxSolValid()</code> returns FALSE, meaning that no relaxation solution
5048 * is available so far, or the lowerbound is larger than the value returned by <code>SCIPgetRelaxSolObj()</code>), then the primal
5049 * solution of the relaxation should be stored inside the data structures of SCIP with <code>SCIPsetRelaxSolVal()</code>,
5050 * <code>SCIPsetRelaxSolVals()</code> or <code>SCIPsetRelaxSolValsSol()</code>. If you set the values one by one, you will need to call
5051 * <code>SCIPmarkRelaxSolValid()</code> to inform SCIP that the solution is complete and valid. With the "includeslp" argument of
5052 * <code>SCIPsetRelaxSolVals()</code>, <code>SCIPsetRelaxSolValsSol()</code> and <code>SCIPmarkRelaxSolValid()</code> you need to tell SCIP
5053 * whether the relaxation included all lp rows. In this case, the solution will be enforced and, if feasible, added to the solution storage if the
5054 * lowerbound of this relaxator is larger than the LP's. You may also call SCIPtrySolFree() directly from the
5055 * relaxation handler to make sure that a solution is added to the solution storage if it is feasible, even if the relaxator does not
5056 * include the LP or another relaxator produced a stronger bound. Also note that when setting the values of the relaxation solution one by one,
5057 * the objective value of the relaxation solution will be updated incrementally. If the whole solution should be updated, using SCIPsetRelaxSolVals()
5058 * instead or calling SCIPclearRelaxSolVals() before setting the first value to reset the solution and the objective value to 0 may help the numerics.
5059 * Furthermore, there is a list of external branching candidates, that can be filled by relaxation handlers and constraint handlers,
5060 * allowing branching rules to take these candidates as a guide on how to split the problem into subproblems. If the relaxation
5061 * solution is enforced, the integrality constraint handler will add external branching candidates for the relaxation solution
5062 * automatically, but the relaxation handler can also directly call <code>SCIPaddExternBranchCand()</code>.
5063 *
5064 * Usually, the RELAXEXEC callback only solves the relaxation and provides a lower (dual) bound through the corresponding pointer and
5065 * possibly a solution through <code>SCIPsetRelaxSolVal()</code> calls.
5066 * However, it may also produce domain reductions, add additional constraints or generate cutting planes. It has the
5067 * following options:
5068 * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
5069 * - adding an additional constraint and stating that the relaxation handler should not be called again on the same
5070 * relaxation (result SCIP_CONSADDED)
5071 * - reducing a variable's domain and stating that the relaxation handler should not be called again on the same
5072 * relaxation (result SCIP_REDUCEDDOM)
5073 * - adding a cutting plane to the LP and stating that the relaxation handler should not be called again on the same
5074 * relaxation (result SCIP_SEPARATED)
5075 * - stating that the relaxation handler solved the relaxation and should not be called again on the same relaxation
5076 * (result SCIP_SUCCESS)
5077 * - interrupting the solving process to wait for additional input, e.g., cutting planes (result SCIP_SUSPENDED)
5078 * - stating that the separator was skipped (result SCIP_DIDNOTRUN).
5079 *
5080 * In the above criteria, "the same relaxation" means that the LP relaxation stayed unmodified. This means in particular
5081 * that no row has been added and no bounds have been modified. For example, changing the bounds of a variable will, as
5082 * long as it was a COLUMN variable, lead to a modification in the LP such that the relaxation handler is called again
5083 * after it returned with the result code SCIP_REDUCEDDOM. If the relaxation solution should be enforced, the relaxation
5084 * handler has to produce a new solution in this case which satisfies the updated LP. If a relaxation handler should only run
5085 * once per node to compute a lower bound, it should store the node of the last relaxation call itself and return
5086 * SCIP_DIDNOTRUN for subsequent calls in the same node.
5087 *
5088 *
5089 * @section RELAX_ADDITIONALCALLBACKS Additional Callback Methods of a Relaxation Handler
5090 *
5091 * The additional callback methods do not need to be implemented in every case. However, some of them have to be
5092 * implemented for most applications, they can be used, for example, to initialize and free private data.
5093 * Additional callbacks can either be passed directly with SCIPincludeRelax() to SCIP or via specific
5094 * <b>setter functions</b> after a call of SCIPincludeRelaxBasic(), see also @ref RELAX_INTERFACE.
5095 *
5096 * @subsection RELAXFREE
5097 *
5098 * If you are using relaxation handler data, you have to implement this method in order to free the relaxation handler
5099 * data. This can be done by the following procedure:
5993 * You also have to initialize the fields in struct SCIP_NlpiData afterwards. For freeing the
5994 * NLPI data, see \ref NLPIFREE.
5995 *
5996 *
5997 * @section NLPI_FUNDAMENTALCALLBACKS Fundamental Callback Methods of an NLPI
5998 *
5999 * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
6000 * an operational algorithm. Most NLPI callbacks are fundamental.
6001 *
6002 * Additional documentation of the callback methods, in particular to their input parameters,
6003 * can be found in \ref type_nlpi.h.
6004 *
6005 * @subsection NLPIFREE
6006 *
6007 * The NLPIFREE callback is executed if the NLP solver interface data structure should be freed, e.g., when a SCIP instance is freed.
6008 *
6009 * @subsection NLPICREATEPROBLEM
6010 *
6011 * The NLPICREATEPROBLEM callback is executed if a particular NLP problem is to be created.
6012 * The callback method should initialize a SCIP_NlpiProblem struct here that corresponds to an empty NLP.
6013 *
6014 * @subsection NLPIFREEPROBLEM
6015 *
6016 * The NLPIFREEPROBLEMPOINTER callback is executed if a particular NLP problem is to be freed.
6017 * The callback method should free a SCIP_NlpiProblem struct here.
6018 *
6019 * @subsection NLPIADDVARS
6020 *
6021 * The NLPIADDVARS callback is executed if a set of variables with lower and upper bounds and names should be added to a particular NLP.
6022 * The callback method must add the new variables behind the previously added variables, if any.
6023 * If NULL is given for the lower bounds arguments, -infinity is assumed as lower bound for each new variable.
6024 * If NULL is given for the upper bounds arguments, +infinity is assumed as upper bound for each new variable.
6025 * It is also permitted to use NULL for the names argument.
6026 *
6027 * @subsection NLPIADDCONSTRAINTS
6028 *
6029 * The NLPIADDCONSTRAINTS callback is executed if a set of constraints should be added to a particular NLP.
6030 * Constraints are specified by providing left- and right-hand-sides, linear coefficients, expressions, and constraint names.
6031 * All of these arguments are optional, giving NULL for left-hand-sides corresponds to -infinity, giving NULL for right-hand-sides corresponds to +infinity.
6032 *
6033 * @subsection NLPISETOBJECTIVE
6034 *
6035 * The NLPISETOBJECTIVE callback is executed to set the objective function of a particular NLP.
6036 *
6037 * @subsection NLPICHGVARBOUNDS
6038 *
6039 * The NLPICHGVARBOUNDS callback is executed to change the bounds on a set of variables of an NLP.
6040 *
6041 * @subsection NLPICHGCONSSIDES
6042 *
6043 * The NLPICHGCONSSIDES callback is executed to change the sides on a set of constraints of an NLP.
6044 *
6045 * @subsection NLPIDELVARSET
6046 *
6047 * The NLPIDELVARSET callback is executed to delete a set of variables from an NLP.
6048 * The caller provides an array in which for each variable it is marked whether it should be deleted.
6049 * In the same array, the method should return the new position of each variable in the NLP, or -1 if it was deleted.
6050 *
6051 * @subsection NLPIDELCONSSET
6052 *
6053 * The NLPIDELCONSSET callback is executed to delete a set of constraints from an NLP.
6054 * The caller provides an array in which for each constraint it is marked whether it should be deleted.
6055 * In the same array, the method should return the new position of each constraint in the NLP, or -1 if it was deleted.
6056 *
6057 * @subsection NLPICHGLINEARCOEFS
6058 *
6059 * The NLPICHGLINEARCOEFS callback is executed to change the coefficients in the linear part of the objective function or a constraint of an NLP.
6060 *
6061 * @subsection NLPICHGEXPR
6062 *
6063 * The NLPICHGEXPR callback is executed to replace the expression of the objective function or a constraint of an NLP.
6064 *
6065 * @subsection NLPICHGOBJCONSTANT
6066 *
6067 * The NLPICHGOBJCONSTANT callback is executed to change the constant offset of the objective function of an NLP.
6068 *
6069 * @subsection NLPISOLVE
6070 *
6071 * The NLPISOLVE callback is executed when an NLP should be solved.
6072 * The solver may use the initial guess provided by \ref NLPISETINITIALGUESS as starting point.
6073 * The status of the solving process and solution can be requested by
6078 * The NLPIGETSOLSTAT callback can be used to request the solution status (solved, infeasible, ...) after an NLP has been solved.
6079 *
6080 * @subsection NLPIGETTERMSTAT
6081 *
6082 * The NLPIGETTERMSTAT callback can be used to request the termination reason (normal, iteration limit, ...) after an NLP has been solved.
6083 *
6084 * @subsection NLPIGETSOLUTION
6085 *
6086 * The NLPIGETSOLUTION callback can be used to request the primal and dual solution values after an NLP solve.
6087 * The method should pass pointers to arrays of variable values to the caller.
6088 * It is possible to return only primal values for the variables, but no values for the dual variables, e.g., if a solver does not compute such values.
6089 *
6090 * @subsection NLPIGETSTATISTICS
6091 *
6092 * The NLPIGETSTATISTICS callback can be used to request the statistical values (number of iterations, time, ...) after an NLP solve.
6093 * The method should fill the provided NLPSTATISTICS data structure.
6094 *
6095 * @section NLPI_ADDITIONALCALLBACKS Additional Callback Methods of an NLPI
6096 *
6097 * The additional callback methods do not need to be implemented in every case.
6098 *
6099 * @subsection NLPICOPY
6100 *
6101 * The NLPICOPY callback is executed if the plugin should be copied, e.g., when a SCIP instance is copied.
6102 *
6103 * It is advisable to implement this callback to make the NLP solver available in sub-SCIPs.
6104 * Note that the sub-NLP heuristic solves NLPs in a sub-SCIP.
6105 *
6106 * @subsection NLPIGETSOLVERPOINTER
6107 *
6108 * The NLPIGETSOLVERPOINTER callback can be used to pass a pointer to a solver specific data structure to the user.
6109 * Return NULL if you do not have a pointer to return.
6110 *
6111 * @subsection NLPIGETPROBLEMPOINTER
6112 *
6113 * The NLPIGETPROBLEMPOINTER callback can be used to pass a pointer to a solver specific data structure of the NLP to the user.
6114 *
6115 * @subsection NLPISETINITIALGUESS
6116 *
6117 * The NLPISETINITIALGUESS callback is executed to provide primal and dual initial values for the variables and constraints of an NLP.
6118 * For a local solver, it is strongly advisable to implement this callback, as these values should be used as a starting point for the search.
6119 * It is possible to pass a NULL pointer for any of the arguments (primal values of variables, dual values of variable bounds, dual values of constraints).
6120 * In this case, the solver should clear previously set starting values and setup its own starting point.
6162 * The expression interpreter has to implement a set of interface method.
6163 * In your "exprinterpret_myad.c", these methods are mostly dummy methods that return error codes.
6164 *
6165 * @subsection SCIPexprintGetName
6166 *
6167 * The SCIPexprintGetName() method should return the name of the expression interpreter.
6168 *
6169 * @subsection SCIPexprintGetDesc
6170 *
6171 * The SCIPexprintGetDesc() method should return a short description of the expression interpreter, e.g., the name of the developer of the code.
6172 *
6173 * @subsection SCIPexprintGetCapability
6174 *
6175 * The SCIPexprintGetCapability() method should return a bitmask that indicates the capabilities of the expression interpreter,
6176 * i.e., whether it can compute gradients and Hessians.
6177 *
6178 * @subsection SCIPexprintCreate
6179 *
6180 * The SCIPexprintCreate() method is called to create an expression interpreter data structure.
6181 * The method should initialize a `struct SCIP_ExprInt` here.
6182 *
6183 * @subsection SCIPexprintFree
6184 *
6185 * The SCIPexprintFree() method is called to free an expression interpreter data structure.
6186 * The method should free a `struct SCIP_ExprInt` here.
6187 *
6188 * @subsection SCIPexprintCompile
6189 *
6190 * The SCIPexprintCompile() method is called to initialize the data structures that are required to evaluate a particular expression.
6191 * The expression interpreter can create and return data that is particular to a given expression in the argument `exprintdata`.
6192 *
6193 * @subsection SCIPexprintFreeData
6194 *
6195 * The SCIPexprintFreeData() method is called to free the data that is particular to a given expression and was possibly created in SCIPexprintCompile().
6196 *
6197 * @subsection SCIPexprintGetExprCapability
6198 *
6199 * The SCIPexprintGetExprCapability() method is called to request the capability to evaluate a specific expression by the expression interpreter.
6200 *
6201 * In cases of user-given expressions, higher order derivatives may not be available for the user-expression,
6202 * even if the expression interpreter could handle these. This method allows to recognize that, e.g., the
6203 * Hessian for an expression is not available because it contains a user expression that does not provide
6204 * Hessians.
6205 *
6206 * @subsection SCIPexprintEval
6207 *
6208 * The SCIPexprintEval() method is called when the value of an expression should be computed for a point.
6209 *
6210 * @subsection SCIPexprintGrad
6211 *
6212 * The SCIPexprintGrad() method is called when the gradient of an expression represented by an expression should be computed for a point.
6213 *
6214 * @subsection SCIPexprintHessianSparsity
6215 *
6216 * The SCIPexprintHessianSparsity() method is called when the sparsity structure of the Hessian matrix should be computed and returned.
6217 * Only the position of nonzero entries in the lower-triangular part of Hessian should be reported.
6218 *
6219 * @subsection SCIPexprintHessian
6220 *
6221 * The SCIPexprintHessian() method is called when the Hessian of an expression should be computed for a point.
6228 * After solving a constraint integer program, SCIP can display statistics tables with information about, e.g., the solving time,
6229 * number of nodes, LP iterations or the number of calls and successes of different plugins via "display statistics" in the shell
6230 * or via SCIPprintStatistics() in the C-interface. There already exists a wide variety of statistics tables which can be activated
6231 * or deactivated on demand, see src/scip/table_default.c. Additionally, the user can implement his/her own statistics tables
6232 * in order to display problem or algorithm specific values.
6233 * \n
6234 * A complete list of all statistics tables contained in this release can be found \ref TABLES "here".
6235 *
6236 * We now explain how users can add their own statistics tables.
6237 * We give the explanation for creating your own source file for each additional statistics table. Of course, you can collect
6238 * different additional statistics tables in one source file.
6239 * Take src/scip/table_default.c, where all default statistics tables are collected, as an example.
6240 * As all other default plugins, the default statistics table plugins and the statistics table template are written in C.
6241 * C++ users can easily adapt the code by using the scip::ObjTable wrapper base class and implement the scip_...() virtual methods
6242 * instead of the SCIP_DECL_TABLE... callback methods.
6243 *
6244 *
6245 * Additional documentation for the callback methods of a statistics table can be found in the file type_table.h.
6246 *
6247 * Here is what you have to do to implement a statistics table (assuming your statistics table is named "mystatisticstable"):
6248 * -# Copy the template files src/scip/table_xyz.c and src/scip/table_xyz.h into files named "table_mystatisticstable.c"
6249 * and "table_mystatisticstable.h".
6250 * \n
6251 * Make sure to adjust your build system such that these files are compiled and linked to your project. \n
6252 * If you are adding a new default plugin, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution.
6253 * -# Use SCIPincludeTableMystatisticstable() in order to include the statistics table into your SCIP instance,
6254 * e.g., in the main file of your project (see, e.g., src/cmain.c in the Binpacking example). \n
6255 * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`.
6256 * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mystatisticstable".
6257 * -# Adjust the \ref TABLE_PROPERTIES "properties of the statistics table".
6258 * -# Define the \ref TABLE_DATA "statistics table data". This is optional.
6259 * -# Implement the \ref TABLE_INTERFACE "interface methods".
6260 * -# Implement the \ref TABLE_FUNDAMENTALCALLBACKS "fundamental callback methods".
6261 * -# Implement the \ref TABLE_ADDITIONALCALLBACKS "additional callback methods". This is optional.
6262 *
6263 *
6264 * @section TABLE_PROPERTIES Properties of a Statistics Table
6265 *
6266 * At the top of the new file "table_mystatisticstable.c" you can find the statistics table properties.
6267 * These are given as compiler defines.
6268 * In the C++ wrapper class, you have to provide the statistics table properties by calling the constructor
6269 * of the abstract base class scip::ObjTable from within your constructor.
6270 * The properties you have to set have the following meaning:
6271 *
6272 * \par TABLE_NAME: the name of the statistics table.
6273 * This name is used in the interactive shell to address the statistics table.
6274 * Additionally, if you are searching for a statistics table with SCIPfindTable(), this name is looked up.
6275 * Names have to be unique: no two statistic tables may have the same name.
6276 *
6277 * \par TABLE_DESC: the description of the statistics table.
6278 * This string is printed as a description of the statistics table in the interactive shell.
6279 *
6280 * \par TABLE_POSITION: the position of the statistics table.
6281 * In the statistics output, the statistics tables will be ordered by increasing position. Compare with the
6282 * default statistics tables in "table_default.c" to find a value which will give you the desired position
6283 * between the default statistics tables. If you give your table a negative position value, it will appear
6284 * before all SCIP statistcs, with a value larger than 20000 it will appear after all default statistics.
6285 *
6286 * \par TABLE_EARLIEST_STAGE: output of the statistics table is only printed from this stage onwards
6287 * The output routine of your statistics table will only be called if SCIP has reached this stage. For
6288 * example, the default table "tree" will only output information starting from SCIP_STAGE_SOLVING, because
6289 * there is no meaningful information available before, while the "presolver" table can already be called
6290 * in SCIP_STAGE_TRANSFORMED.
6291 *
6292 * @section TABLE_DATA Statistics Table Data
6293 *
6294 * Below the header "Data structures" you can find a struct which is called "struct SCIP_TableData".
6295 * In this data structure, you can store the data of your statistics table. For example, you should store the adjustable
6296 * parameters of the statistics table in this data structure.
6297 * If you are using C++, you can add statistics table data as usual as object variables to your class.
6298 * \n
6299 * Defining statistics table data is optional. You can leave the struct empty.
6300 *
6301 *
6302 * @section TABLE_INTERFACE Interface Methods
6303 *
6304 * At the bottom of "table_mystatisticstable.c" you can find the interface method SCIPincludeTableMystatisticstable(), which also
6305 * appears in "table_mystatisticstable.h".
6306 * \n
6307 * This method only has to be adjusted slightly.
6308 * It is responsible for notifying SCIP of the presence of the statistics table by calling the method
6309 * SCIPincludeTable().
6310 *
6311 * The interface method is called by the user, if (s)he wants to include the statistics table, i.e., if (s)he wants to use the statistics table in an
6312 * application.
6313 *
6314 * If you are using statistics table data, you have to allocate the memory for the data at this point.
7158/**@page CONCSCIP How to use the concurrent solving mode
7159 *
7160 * @section Overview
7161 *
7162 * In \SCIP 4.0 a new feature has been added that allows to run multiple \SCIP instances with different settings
7163 * on one problem in parallel. To use this feature \SCIP has to be compiled with an additional make option to
7164 * enable the threading functionality (e.g. TPI=tny, see \ref MAKE).
7165 * Then, a concurrent solve can be started by using the <code>concurrentopt</code> command instead of the <code>optimize</code> command
7166 * in the \SCIP shell, or by calling the interface function SCIPsolveParallel().
7167 * To configure the behavior of the concurrent solving mode there are new parameters in the category <code>concurrent/</code>
7168 * and <code>parallel/</code> which will be explained here shortly.
7169 *
7170 * @section CONTROLNTHREADS Controlling the number of threads
7171 *
7172 * The parameters <code>parallel/maxnthreads</code> and <code>parallel/minnthreads</code> can be used to configure the number of threads
7173 * that sould be used for solving. \SCIP will try to use the configured maximum number of threads. If the
7174 * problem that is currently read is too large \SCIP will automatically use fewer threads, but never
7175 * go below the configured minimum number of threads.
7176 *
7177 * @section USEEMPHSETTINGS Using emphasis settings
7178 *
7179 * The parameters <code>concurrent/scip.../prefprio</code> configure which concurrent solvers should be used.
7180 * The concurrent solver <code>scip</code> will use the same settings as the \SCIP instance configured by the user.
7181 * The other concurrent solvers, e.g. <code>scip-feas</code>, will load the corresponding emphasis setting.
7182 * The behavior of the prefprio parameter is as follows: If it is set to 1.0 for <code>scip-feas</code> and
7183 * <code>scip-opti</code>, and to 0.0 for every other concurrent solver, then the threads will be evenly
7184 * distributed between the two types <code>scip-feas</code> and <code>scip-opti</code>. An example: if 4 threads are used each of these concurrent
7185 * solvers will use 2 threads. If the <code>prefprio</code> for one solver is set to 0.33 and the other is set to 1.0, then the former will use 1 thread
7186 * and the latter will use 3 threads of the 4 available threads.
7190 * To use custom settings for the concurrent solvers there is the parameter <code>concurrent/paramsetprefix</code>. If custom parameters
7191 * should be loaded by the concurrent solvers, then it must point to the folder where they are located (including a path separator at the end).
7192 * The parameter settings must be named after the concurrent solvers, e.g. if only the concurrent solver <code>scip</code> is used
7193 * they should be named <code>scip-1</code>, <code>scip-2</code>, <code>scip-3</code>. When different types of concurrent solvers are used the counter
7194 * starts at one for each of them, e.g. <code>scip-1</code> and <code>scip-feas-1</code>.
7201/**@page DECOMP How to provide a problem decomposition
7202 *
7203 * Most mixed-integer programs have sparse constraint matrices in the sense that most columns and rows have only very few nonzero entries,
7204 * maybe except for a few outlier columns/rows with many nonzeros.
7205 * A decomposition identifies subproblems (subsets of rows and columns) that are only linked to each other via a set of linking rows and/or linking
7206 * columns, but are otherwise independent.
7207 * The special case of completely independent subproblems (with no linking rows and columns), for example, can be solved by solving
7208 * the much smaller subproblems and concatenating their optimal solutions.
7209 * This case has already been integrated into SCIP as a successful presolving technique (see @ref cons_components.c).
7210 * Another use of decomposition within SCIP is the @ref BENDDECF "Benders Decomposition framework".
7211 *
7212 * Since SCIP 7.0, it is easier to pass user decompositions to SCIP that can be used within Benders decomposition or by user algorithms.
7213 * This page introduces the struct SCIP_DECOMP and gives examples how to create and use it.
7214 *
7215 * @section DECOMP_OVERVIEW Overview
7216 *
7217 * In the following, we present decompositions of mixed-integer programs. However, the generalization to Constraint Integer Programs is straightforward.
7218 *
7219 * Concretely, for \f$k \geq 0\f$ we call a partition \f$\mathcal{D}=(D^{\text{row}},D^{\text{col}})\f$ of the rows and columns of the constraint matrix \f$A\f$ into \f$k + 1\f$ pieces each,
7224 * a decomposition of \f$A\f$ if \f$D^{\text{row}}_{q} \neq \emptyset\f$, \f$D^{\text{col}}_{q} \neq \emptyset\f$ for \f$q \in \{1,\dots,k\}\f$ and if it holds for all \f$i\in D^{\text{row}}_{q_{1}}, j\in D^{\text{col}}_{q_{2}}\f$ that \f$a_{i,j} \neq 0 \Rightarrow q_{1} = q_{2}\f$.
7225 * The special rows \f$L^{\text{row}}\f$ and columns \f$L^{\text{col}}\f$, which may be empty, are called linking rows and linking columns, respectively.
7226 * In other words, the inequality system \f$A x \geq b\f$ can be rewritten
7227 * with respect to a decomposition \f$\mathcal{D}\f$ by a suitable permutation of the rows
7228 * and columns of \f$A\f$ as equivalent system
7299 * is part of subproblem \f$q\f$, the handling of the linking variables/constraints depends on the chosen application context.
7300 * For example, in the heuristic @ref heur_padm.c several smaller subproblems are solved multiple times to get a feasible solution.
7301 * Also the @ref BENDDECF "Benders' decomposition framework" was extended with release 7.0 to use user decompositions.
7302 *
7303 * @section DECOMP_CREATION Creation via SCIP-API
7304 *
7305 * There are two different ways to provide a decomposition in SCIP.
7306 * It can be created with the SCIP-API or it can be read from a file.
7307 *
7308 * To create it with the API, the user must first create a decomposition with SCIPcreateDecomp() specifying
7309 * whether the decomposition belongs to the original or transformed problem and the number of blocks.
7310 * Then the variables and constraints can be assigned to one block or to the linking rows/columns by calling
7311 * SCIPdecompSetVarsLabels() and SCIPdecompSetConsLabels(), respectively.
7312 * To complete the decomposition or to ensure that it is internally consistent, SCIPcomputeDecompVarsLabels() or
7313 * SCIPcomputeDecompConsLabels() can be called.
7314 * Note that SCIPcomputeDecompVarsLabels() will ignore the existing variable labels and computes again the labels based on the constraint labels only;
7315 * SCIPcomputeDecompConsLabels() works in the same way and ignores the existing constraint labels.
7316 *
7317 * After the decomposition has been successfully created, it can be saved for later use in the DecompStore using SCIPaddDecomp().
7318 * Access to all decompositions in the DecompStore is possible with SCIPgetDecomps().
7319 *
7320 * @section DECOMP_READDEC Reading a decomposition from a file
7321 *
7322 * Alternatively, after a problem has been read, a related decomposition can be read from a dec-file.
7323 * Please refer to the @ref reader_dec.h "DEC file reader" for further information about the required file format.
7324 * Upon reading a valid dec-file, a decomposition structure is created, where the corresponding variable labels are inferred from the constraint labels, giving precedence to block over linking constraints.
7325 *
7326 * @section DECOMP_BENDERS Use for Benders
7327 *
7328 * If the variables should be labeled for the application of @ref BENDDECF "Benders' decomposition", the decomposition must be explicitly flagged by setting the parameter decomposition/benderslabels to TRUE.
7329 * With this setting, the variable's labeling takes place giving precedence to its presence in linking constraints over its presence in named blocks.
7330 *
7331 * @section DECOMP_TRANS Decomposition after problem transformation
7332 *
7333 * As the problem's constraints are constantly changing, or possibly deleted, during presolving, the constraints' labeling must be triggered again.
7334 * Therefore, SCIP automatically transforms all user decompositions at the beginning of the root node based on the variables' labels.
7366 * where \f$e_{q}\f$ is the number of inner edges within block \f$q\f$ and \f$m\f$ is the total number of edges.
7367 * The presence of an inner edge is identified through the presence of a variable in a constraint,
7368 * both—the variable and the constraint—belonging to the same block.
7369 * - the block graph statistics: A block graph is constructed with the aim of depicting the connection between the different blocks in a decomposition through the existing linking variables in the constraints.
7370 * Note that the linking constraints are intentionally skipped in this computation.
7371 * \f$ G = (V,E) \f$ denotes a block graph, with vertex set \f$V\f$ and edge set \f$E\f$.
7372 * Each vertex in the graph represents a block in the decomposition; \f$V = \{v_{1},\dots,v_{k}\}\f$.
7373 * An edge \f$e = \{ v_{s},v_{t} \}\f$ is added to \f$G\f$, if and only if there exists a column \f$\ell \in L^{\text{col}}\f$, a row \f$i \in D^{\text{row}}_{s}\f$
7374 * and a row \f$j \in D^{\text{row}}_{t}\f$, such that \f$a_{i,\ell} \neq 0\f$ and \f$a_{j,\ell} \neq 0\f$.
7375 * From the constructed graph, the number of edges, articulation points and connected components are computed, together with the maximum and minimum degree.
7376 * Note that building the block graph can become computationally expensive with large and dense decompositions.
7377 * Thus, it is possible through a user parameter <code>decomposition/maxgraphedge</code> to define a maximum edge limit.
7378 * The construction process will be interrupted once this limit is reached, in which case only approximate estimations of the block graph statistics will be displayed and accompanied with a warning message.
7474 * - the subproblem is convex: \f$g_i(x,y)\f$ convex on \f$X\times Y\f$ if \f$u_i<\infty\f$, \f$g_i(x,y)\f$ concave on \f$X\times Y\f$ if \f$\ell_i>-\infty\f$, and \f$Y=\mathbb{R}^m\f$, or
7475 * - the first stage variables are of binary type: \f$ X \subseteq \{0,1\}^n \f$.
7476 *
7477 * This framework can be used in four different
7478 * ways: inputting an instance in the SMPS file format, using the default Benders' decomposition implementation
7479 * (see src/scip/benders_default.c), implementing a custom Benders' decomposition plugin (see \ref BENDER), or by using
7480 * the Benders' decomposition mode of GCG.
7481 * An overview of how to use each of these methods will be provided in this section.
7482 *
7483 * @section BENDERSSMPS Inputting an instance in the SMPS file format.
7484 *
7485 * As part of the Benders' decomposition framework development, a reader for instances in the SMPS file format has been
7486 * implemented (see src/scip/reader_smps.c). The details regarding the SMPS file format can be found at:
7487 *
7488 * Birge, J. R.; Dempster, M. A.; Gassmann, H. I.; Gunn, E.; King, A. J. & Wallace, S. W.
7489 * A standard input format for multiperiod stochastic linear programs
7490 * IIASA, Laxenburg, Austria, WP-87-118, 1987
7491 *
7492 * In brief, the SMPS file format involves three different files:
7493 * - A core file (.cor): a problem instance in MPS format that is the core problem of a stochastic program.
7494 * - A time file (.tim): partitions the variables and constraints into the different stages of the stochastic program
7495 * - A stochastic file (.sto): describes the scenarios for each stage.
7496 *
7497 * The STO reader (see src/scip/reader_sto.c) constructs the stochastic program using the information from the core and
7498 * time files. By default, the STO reader will construct the deterministic equivalent of the stochastic program. A
7499 * parameter is provided "reading/sto/usebenders" that will inform the STO reader to apply Benders' decomposition to the
7500 * input stochastic program.
7501 *
7502 * @section BENDERSDEFAULT Using the default Benders' decomposition plugin.
7503 *
7504 * A default implementation of a Benders' decomposition plugin has been included in \SCIP 6.0 (see
7505 * src/scip/benders_default.c). In order to use the default plugin, the user must create SCIP instances of the master
7506 * problem and subproblems. The subproblems must also contain a copy of the master problem variables, since these are
7507 * fixed to the master problem solution values during the subproblem solving loop. These SCIP instances for the master
7508 * and subproblems are passed to the default plugin by calling SCIPcreateBendersDefault().
7509 *
7510 * The mapping between the master and subproblem variables is performed automatically. The default solving and cut
7511 * generation methods are applied to solve the input problem. It is important to note that the mapping between the
7512 * master and subproblem variables relies on the variable names. The variables of the subproblem corresponding to
7513 * master problem variables must have the same name in both problems.
7514 *
7515 * The CAP (stochastic capacitated facility location problem) example demonstrates the use of the default Benders'
7516 * decomposition implementation within a project.
7517 *
7518 * @section BENDERSCUSTOM Implementing a custom Benders' decomposition implementation.
7519 *
7520 * A custom Benders' decomposition requires the implementation of a Benders' decomposition plugin. The key aspects for
7521 * implementing a custom Benders' decomposition plugin are explained in \ref BENDER.
7522 *
7523 * @section BENDERSGCG Using the Benders' decomposition mode of GCG
7524 *
7525 * In GCG 3.0, a Benders' decomposition mode has been implemented. This mode takes the decomposition found by the
7526 * detection schemes of GCG and applies Benders' decomposition. Using GCG it is possible to apply Benders' decomposition
7527 * to general problem without having to manually construct the decompositions.
7533/**@page PROBINGDIVING How to use probing and diving mode
7534 *
7535 * SCIP contains two methods to perform a temporary dive in the branch-and-bound tree: the diving mode and the probing mode.
7536 * Both methods enable the modification of variable bounds, addition of new constraints, or adjustments to the objective function.
7537 * Whereas the diving mode works directly on the LP structure, the probing mode creates temporary branch-and-bound nodes, which makes it possible to perform backtracks during a dive.
7538 * Probing allows to perform domain propagation at the temporary nodes and provides the ability to solve the LP by column generation if a pricer plugin is implemented; neither is possible in diving mode.
7539 *
7540 * After entering diving or probing mode by calling SCIPstartDive() and SCIPstartProbing(), respectively, there exist various functions that allow the user to temporarily change the LP.
7541 * An overview for diving can be found here[https://www.scipopt.org/doc/html/group__PublicLPDivingMethods.php] and for the probing mode here[https://scipopt.org/doc/html/group__PublicProbingMethods.php].
7542 * To reset all changes, the respective mode needs to be ended by calling SCIPendDive() and SCIPendProbing(), respectively.
7543 *
7544 * Note that, although the state of the LP and the problem is reset after ending probing and diving, both modes can have several effects on the subsequent solving process.
7545 * In some situations, when the LP is infeasible for example, conflict analysis will be run in both probing and diving modes, which can lead to globally valid conflict constraints that are then added to the main solving process.
7546 * Similarly, the function SCIPpropagateProbing() might find globally valid bound changes, which are added to the main SCIP and considered in the subsequent solving process.
7547 * Another way to leverage insights found during probing or diving is to update pseudo costs during both modes, helping make better branching decisions.
7548 * This is controlled by setting the parameter "divingpscosts" to TRUE, which is done in the default settings of SCIP.
7549 * Moreover, if the LP was not solved to optimality before entering diving mode (or the parameter "resolverestore" is set to TRUE), the LP is resolved to reset the solution.
7550 * In some cases, such as when dealing with a numerically difficult instance, this might lead to a different LP state.
7551 * Finally, during probing, global variable statistics can be collected by calling SCIPenableVarHistory() after starting probing.
7552 * Since these statistics can be used for decision-making in SCIP, enabling their collection can have an effect on the solving process after probing ends.
7756 * As you can see, both pointers and integers are checked for valid values at the beginning of the
7757 * function <code>consCatchEvent()</code>. This is particularly important for, e.g., array indices like
7758 * the variable <code>pos</code> in this example, where using the <code>consdata->vars[pos]</code>
7759 * pointer could result in unexspected behaviour
7760 * if the asserted precondition on <code>pos</code> were not matched and <code>pos</code> were an arbitrary index
7761 * outside the array range.
7762 *
7763 * - In order to activate assertions, use the <b>Debug mode</b> by compiling SCIP via
7764 * \code
7765 * cmake -DCMAKE_BUILD_TYPE=Debug
7766 * \endcode
7767 * or the Makefile equivalent
7768 * \code
7769 * make OPT=dbg
7770 * \endcode and run the code. See \ref CMAKE and \ref MAKE for further information about compiler options for SCIP.
7771 * As a rule of thumb, Spending only little extra time on
7772 * asserting preconditions saves most of the time spent on debugging!
7773 *
7774 * - Turn on <b>additional debug output</b> by adding the line
7775 * \code
7776 * #define SCIP_DEBUG
7777 * \endcode
7778 * at the top of SCIP files you want to analyze. This will output messages included in the code using
7779 * <code>SCIPdebugMsg(scip, ...)</code> (or <code>SCIPdebugMessage()</code>), see \ref EXAMPLE_1.
7780 * We recommend to also use <code>SCIPdebugMsg(scip, ...)</code> in your own code for being able to activate
7781 * debug output in the same way.
7782 * - If available on your system, we recommend to use a debugger like <code>gdb</code>
7783 * to trace all function calls on the stack,
7784 * display values of certain expressions, manually break the running code, and so forth.
7785 * - If available on your system, you can use software like <a href="http://valgrind.org">valgrind</a> to check for uninitialized
7786 * values or segmentation faults.
7787 * - For checking the usage of SCIP memory, you can use
7788 * <code>SCIPprintMemoryDiagnostic()</code>. This outputs memory that is currently in use,
7789 * which can be useful after a <code>SCIPfree()</code> call.
7790 * - If there are memory leaks for which you cannot detect the origin, you can recompile your code with the option <code>cmake -DNOBLKBUFMEM=on</code>
7791 * (or <code>make NOBLKBUFMEM=true</code> if you are using the Makefile system.
7792 * Also for the Makefile system, do not forget to clean your code before with <code>make OPT=... LPS=... clean</code>)
7793 * Only with that change, valgrind (or similar) reliably helps
7794 * to detect leaked memory.
7795 * - If your code cuts off a feasible solution, but you do not know which component is responsible,
7796 * you can use the debugging mechanism (see \ref EXAMPLE_2). Therefore, a given solution is read and it
7797 * is checked for every reduction, whether the solution will be pruned globally.
7798 *
7799 * @section EXAMPLE_1 How to activate debug messages
7800 * For example, if we include a <code>\#define SCIP_DEBUG</code> at the top of \ref heur_oneopt.c, recompile SCIP
7801 * in Debug mode, and run the SCIP interactive shell to solve p0033.mps from the
7802 * <a href="http://miplib2010.zib.de/miplib3/miplib.html">MIPLIB 3.0</a> , we get some output like:
7803 *
7804 * \include debugexamples/example1.txt
7805 *
7806 * @section EXAMPLE_2 How to add a debug solution
7807 *
7808 * Continuing the example above, we finish the solving process.
7809 * The optimal solution can now be written to a file:
7810 * \include debugexamples/example2_1.txt
7811 *
7812 * If we afterwards recompile SCIP with the additional compiler flag <code>cmake -DDEBUGSOL=on</code> (<code>make DEBUGSOL=true</code> in the Makefile system),
7813 * set the parameter <code>misc/debugsol = check/p0033.sol</code>, and run SCIP again it will output:
7814 * \include debugexamples/example2_2.txt
7815 * Further debug output would only appear, if the solution was cut off in the solving process.
7822 * The SCIP object goes through different stages during the solving process, the transitions from one to the next are presented in the following diagram.
7823 * \image html stages.png
7824 * More exhaustively, the stages are:
7825 * \code
7826 * SCIP_STAGE_INIT = 0, /**< SCIP data structures are initialized, no problem exists
7827 * SCIP_STAGE_PROBLEM = 1, /**< the problem is being created and modified
7828 * SCIP_STAGE_TRANSFORMING = 2, /**< the problem is being transformed into solving data space
7829 * SCIP_STAGE_TRANSFORMED = 3, /**< the problem was transformed into solving data space
7830 * SCIP_STAGE_INITPRESOLVE = 4, /**< presolving is initialized
7831 * SCIP_STAGE_PRESOLVING = 5, /**< the problem is being presolved
7832 * SCIP_STAGE_EXITPRESOLVE = 6, /**< presolving is exited
7833 * SCIP_STAGE_PRESOLVED = 7, /**< the problem was presolved
7834 * SCIP_STAGE_INITSOLVE = 8, /**< the solving process data is being initialized
7835 * SCIP_STAGE_SOLVING = 9, /**< the problem is being solved
7836 * SCIP_STAGE_SOLVED = 10, /**< the problem was solved
7837 * SCIP_STAGE_EXITSOLVE = 11, /**< the solving process data is being freed
7838 * SCIP_STAGE_FREETRANS = 12, /**< the transformed problem is being freed
7839 * SCIP_STAGE_FREE = 13 /**< SCIP data structures are being freed
7840 * \endcode
7841 * Most functions can be called in a subset of the stages, this is then documented, a runtime check is often added and will throw a \ref SCIP_INVALIDCALL if the stage is not allowed.
8023 * \arg <code>TIME</code> - time limit for each test instance in seconds [default: 3600]
8024 * \arg <code>SETCUTOFF</code> - if set to '1', an optimal solution value (from the <code>.solu</code>-file) is used as objective limit [default: 0]
8025 * \arg <code>THREADS</code> - the number of threads used for solving LPs, if the linked LP solver supports multithreading [default: 1]
8026 * \arg <code>VALGRIND</code> - run valgrind on the SCIP binary; errors and memory leaks found by valgrind are reported as fails [default: "false"]
8027 *
8028 *
8029 * @section COMPARE Comparing test runs for different settings
8030 *
8031 * Often test runs are performed on the basis of different settings. In this case, it is useful to
8032 * have a performance comparison. For this purpose, we can use the <code>allcmpres.sh</code> script in
8033 * the @c check directory.
8034 *
8035 * Suppose, we performed our test run with two different settings, say <code>fast.set</code> and
8036 * <code>slow.set</code>. Assuming that all other parameters (including the SCIP binary), were the same,
8037 * we may have the following <code>res</code>-files in the directory <code>scip/check/results/</code>
8149 * In this case, the test with respect to the number of found feasible solutions is irrelevant, since their number is
8150 * equal. In particular, the null hypothesis gets accepted (i.e., there is no difference in the settings - this is
8151 * marked by "X").
8152 *
8153 * With respect to the number of instances solved to optimality within the timelimit, we have that \f$0.005 < p <=
8154 * 0.05\f$ (marked by <tt>p ~ (0.005, 0.05)</tt>). Thus, there is some evidence that the null hypothesis is false, i.e., the
8155 * settings perform differently; this is marked by "!". In the concrete case, we have 230 instances, all of which are
8156 * solved by setting \c S2, but only 224 by setting \c S1.
8157 *
8158 * @subsection Wilcoxon Wilcoxon signed rank test
8159 *
8160 * Assume that we compare two settings \c S1 and \c S2 with respect to their solution times (within the time limit). We
8161 * generate a sorted list of the ratios of the run times, where ratios that are (absolutely or relatively) within 1\%
8162 * of 1.0 are discarded, and ratios between 0.0 and 0.99 are replaced with their negative inverse in order to
8163 * obtain a symmetric distribution for the ratios around the origin.
8164 * We then assign ranks 1 to \c N to the remaining \c N data points in nondecreasing
8165 * order of their absolute ratio. This yields two groups \c G1
8166 * and \c G2 depending on whether the ratios are smaller than -1.0 or larger than 1.0 (\c G1 contains the instances for which
8167 * setting \c S1 is faster). Then the sums of the ranks in groups \c G1 and \c G2 are computed, yielding values \c R1
8168 * and \c R2, respectively.
8169 *
8170 * The Wilcoxon test statistic is then
8171 * \f[
8172 * z = \frac{\min(R1, R2) - \frac{N(N+1)}{4}}{\sqrt{\frac{N(N+1)(2N+1)}{24}}},
8173 * \f]
8174 * which we assume to be (approximately) normally distributed (with zero mean) and allows to compute the probability
8175 * \f$p\f$ that one setting is faster than the other. (Note that for \f$N \leq 60\f$, we apply a correction by
8176 * subtracting 0.5 from the numerator).
8177 *
8178 * As an example consider the following output:
8179 * \code
8180 * Wilcoxon (time) z -0.1285, 0.05 <= p X
8181 * Wilcoxon (nodes) z -11.9154, p < 0.0005 !!!
8182 * \endcode
8183 * While the \f$z\f$-value is close to zero for the run time, it is extremely negative regarding the solving nodes. This latter
8184 * tendency for the number of nodes is significant on a 0.05 % level, i.e., the probability \f$p\f$ that setting \c S1 uses more
8185 * nodes than setting \c S2 is negligible (this null hypothesis is rejected - marked by "!!!").
8186 *
8187 * However, the null hypothesis is not rejected with respect to the run time. In the concrete case, setting \c S1 has a
8188 * shifted geometric mean of its run times (over 230 instances) of 248.5, for \c S2 it is 217.6. This makes a ratio of
8189 * 0.88. Still - the null hypothesis is not rejected.
8190 *
8191 * @section SOLVER Testing and Evaluating using GAMS
8192 *
8193 * Analogously to the target <code>test</code> there is another target to run automated tests with <a href="http://www.gams.com/">gams</a>
8194 * \code
8195 * make testgams GAMSSOLVER=xyz
8196 * \endcode
8197 * For this target, the option GAMSSOLVER has to be given to specify the name of a GAMS solver to run, e.g. GAMSSOLVER=SCIP.
8198 * Additional advanced options specific to this target are:
8199 * GAMS to specify the GAMS executable (default: gams),
8200 * GAP to specify a gap limit (default: 0.0),
8201 * CLIENTTMPDIR to specify a directory where GAMS should put its scratch files (default: /tmp),
8202 * CONVERTSCIP to specify a SCIP which can be used to convert non-gams files into gams format (default: bin/scip, if existing; set to "no" to disable conversion).
8203 * The following options are NOT supported (and ignored): DISPFREQ, FEASTOL, LOCK.
8204 * A memory limit (MEM option) is only passed as workspace option to GAMS, but not enforced via ulimit (it's up to the solver to regard and obey the limit).
8205 *
8206 * Note: This works only if the referred programs are installed globally on your machine.
8207 *
8208 * The above options like <code>TIME</code> are also available for gams.
8209 *
8210 * After the testrun there should be an <code>.out</code>, an <code>.err</code> and a <code>.res</code> file
8211 * with the same basename as described above.
8212 *
8213 * Furthermore you can also use the script <code>allcmpres.sh</code> for comparing results.
8214 *
8215 * @section PYTHON Testing using PySCIPOpt
8216 *
8217 * To run a python script that uses PySCIPOpt with <code>make test</code> or <code>make testcluster</code>, one has to
8218 * specify the python code to execute with the option <code>EXECUTABLE=/full/path/to/python-script.py</code>.
8219 * Note that <code>python-script.py</code> must be an executable file.
8220 * In addition, one <b>must</b> specify which python it should run with the option <code>PYTHON=my-python</code>.
8221 * The reason for this is that one usually installs PySCIPOpt in a virtual environment, thus only the python of the
8222 * virtual environment will work with the python script.
8223 *
8224 * The scripts work in such a way that they pass information to SCIP like the setting files, the instance name, and some other options.
8225 * It is the responsability of the python script <code>python-script.py</code> to parse this information.
8226 * Thus, you need to modify your python script to read the setting files and the other options provided by the testing scripts.
8227 * An example of how to do this is provided in <code>scip/check/scip-runner.py</code>.
8228 * One should either modify <code>scip/check/scip-runner.py</code> or include the <code>build_model()</code> function
8229 * into your script to correctly read the options passed by the scripts.
8230 *
8231 * An example of how to run the tests is
8232 * \code
8233 * make test EXECUTABLE=/full/path/to/scip/check/scip-runner.py PYTHON=python
9417 * <tr><td>\ref reader_cnf.h "CNF format"</td> <td>DIMACS CNF (conjunctive normal form) file format used for example for SAT problems</td></tr>
9418 * <tr><td>\ref reader_diff.h "DIFF format"</td> <td>for reading a new objective function for mixed-integer programs</td></tr>
9419 * <tr><td>\ref reader_fzn.h "FZN format"</td> <td>FlatZinc is a low-level solver input language that is the target language for MiniZinc</td></tr>