Scippy

SCIP

Solving Constraint Integer Programs

xternal.c
Go to the documentation of this file.
1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
2 /* */
3 /* this file is part of the program and library */
4 /* SCIP --- Solving Constraint Integer Programs */
5 /* */
6 /* 2002-2014 Konrad-Zuse-Zentrum */
7 /* fuer Informationstechnik Berlin */
8 /* */
9 /* SCIP is distributed under the terms of the ZIB Academic License. */
10 /* */
11 /* You should have received a copy of the ZIB Academic License */
12 /* along with SCIP; see the file COPYING. If not email to scip@zib.de. */
13 /* */
14 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
15 
16 /**@file xternal.c
17  * @brief main document page
18  * @author Tobias Achterberg
19  * @author Timo Berthold
20  * @author Gerald Gamrath
21  * @author Stefan Heinz
22  * @author Gregor Hendel
23  * @author Mathias Kinder
24  * @author Marc Pfetsch
25  * @author Stefan Vigerske
26  * @author Robert Waniek
27  * @author Kati Wolter
28  * @author Michael Winkler
29  */
30 
31 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
32 
33 /**@mainpage Overview (\OTHERDOCU)
34  *
35  * \OTHERDOCUTEXT
36  *
37  *
38  *
39  * @section WHATISSCIP What is SCIP?
40  *
41  * SCIP is a framework to solve constraint integer programs (CIPs). In particular,
42  *
43  * - SCIP is a branch-and-cut-and-price framework,
44  * - incorporates a full-scale mixed integer programming (MIP) solver, and
45  * - incorporates a full-scale mixed integer quadratically constrained programming (MIQCP) solver.
46  *
47  * See the web site of <a href="http://scip.zib.de">SCIP</a> for more information about licensing and to download SCIP.
48  *
49  * SCIP is developed together with <a href="http://www3.mathematik.tu-darmstadt.de/ags/optimierung/research/discrete-optimization.html">TU Darmstadt</a> and
50  * <a href="http://www.am.uni-erlangen.de/wima/">University of Erlangen-N&uuml;rnberg (Chair of EDOM)</a>
51  * and has more than 500,000 lines of C code.
52  *
53  * @section GETTINGSTARTED Getting started
54  *
55  * - \ref MAKE "Installation information / Makefiles"
56  * - \ref LICENSE "License"
57  *
58  * - \ref SHELL "Tutorial: the interactive shell"
59  * - \ref FILEREADERS "Readable file formats"
60  * - \ref START "How to start a new project"
61  * - \ref EXAMPLES "Examples"
62  *
63  * @section FURTHERINFORMATION References
64  *
65  * - \ref PUBLICMETHODS "List of callable functions"
66  * - \ref PARAMETERS "List of all SCIP parameters"
67  *
68  * - \ref DOC "How to search the documentation for interface methods"
69  * - \ref FAQ "Frequently asked questions (FAQ)"
70  * - \ref TEST "How to run automated tests with SCIP"
71  * - \ref COUNTER "How to use SCIP to count feasible solutions"
72  *
73  *
74  * @section PROGRAMMING Programming with SCIP
75  *
76  * @subsection CODINGBASICS Coding basics for SCIP
77  *
78  * - \ref CODE "Coding style guidelines"
79  * - \ref OBJ "Creating, capturing, releasing, and adding data objects"
80  * - \ref DEBUG "Debugging"
81  *
82  * @subsection HOWTOADD How to add ...
83  * - \ref CONS "Constraint handlers"
84  * - \ref PRICER "Variable pricers"
85  * - \ref PRESOL "Presolvers"
86  * - \ref SEPA "Separators"
87  * - \ref PROP "Propagators"
88  * - \ref BRANCH "Branching rules"
89  * - \ref NODESEL "Node selectors"
90  * - \ref HEUR "Primal heuristics"
91  * - \ref RELAX "Relaxation handlers"
92  * - \ref READER "File readers"
93  * - \ref DIALOG "Dialogs"
94  * - \ref DISP "Display columns"
95  * - \ref EVENT "Event handler"
96  * - \ref NLPI "Interfaces to NLP solvers"
97  * - \ref EXPRINT "Interfaces to expression interpreters"
98  * - \ref CONF "Conflict analysis"
99  * - \ref PARAM "additional user parameters"
100  *
101  *
102  * @section FURTHERINFO Further information
103  *
104  * @subsection CHG Changes between different versions of SCIP
105  * - \ref CHANGELOG "Change log"
106  * - \ref RELEASENOTES "Release notes"
107  * - \ref CHG7 "Interface changes between version 3.0 and 3.1"
108  * - \ref CHG6 "Interface changes between version 2.1 and 3.0"
109  * - \ref CHG5 "Interface changes between version 2.0 and 2.1"
110  * - \ref CHG4 "Interface changes between version 1.2 and 2.0"
111  * - \ref CHG3 "Interface changes between version 1.1 and 1.2"
112  * - \ref CHG2 "Interface changes between version 1.0 and 1.1"
113  * - \ref CHG1 "Interface changes between version 0.9 and 1.0"
114  *
115  * @subsection AUTHORS SCIP Authors
116  * - <a class="el" href="http://scip.zib.de/#developers">Developers</a>
117  *
118  * @version 3.1.1
119  *
120  * \image html scippy.png
121  *
122  */
123 
124 /** @page EXAMPLES Examples projects
125  *
126  * SCIP contains several examples that demonstrate its usage. They are contained in the &quot;examples&quot; directory
127  * in the source code distribution.
128  *
129  * @section BRANCHANDPRICE Branch-and-price
130  *
131  * <table>
132  * <tr>
133  * <td>
134  * <a href="http://scip.zib.de/doc/examples/Binpacking"><b>Binpacking</b></a>
135  * </td>
136  * <td>
137  * An implementation of the column generation approach for the binpacking problem. It includes a customized reader,
138  * Ryan/Foster branching rule, (global) problem data, variable data, and constraint handler.
139  * </td>
140  * </tr>
141  * <tr>
142  * <td>
143  * <a href="http://scip.zib.de/doc/examples/Coloring"><b>Coloring</b></a>
144  * </td>
145  * <td>
146  * An implemenation of the column generation approach for graph coloring of Mehrotra and Trick.
147  * </td>
148  * </tr>
149  * <tr>
150  * <td>
151  * <a href="http://scip.zib.de/doc/examples/VRP"><b>VRP</b></a>
152  * </td>
153  * <td>
154  * A solver for a simple capacity-constrained vehicle routing problem, which is based on pricing tours via a dynamic
155  * programming algorithm.
156  * </td>
157  * </tr>
158  * </table>
159  *
160  * @section BRANCHANDCUT Branch-and-cut
161  *
162  * <table>
163  * <tr>
164  * <td>
165  * <a href="http://scip.zib.de/doc/examples/LOP"><b>LOP</b></a>
166  * </td>
167  * <td>
168  * An example for implementing a constraint handler.
169  * </td>
170  * </tr>
171  * <tr>
172  * <td>
173  * <a href="http://scip.zib.de/doc/examples/TSP"><b>TSP</b></a>
174  * </td>
175  * <td>
176  * A short implementations of a constraint handler, two easy combinatorial heuristics, a file reader, etc. which
177  * demonstrate the usage of SCIP as a branch-and-cut-framework for solving traveling salesman problem instances.
178  * </td>
179  * </tr>
180  * </table>
181  *
182  * @section CALLABLELIBRARY Callable library
183  *
184  * <table>
185  * <tr>
186  * <td>
187  * <a href="http://scip.zib.de/doc/examples/CallableLibrary"><b>CallableLibrary</b></a>
188  * </td>
189  * <td>
190  * An example showing how to setup constraints (esp. nonlinear ones) when using SCIP as callable library.
191  * </td>
192  * </tr>
193  * <tr>
194  * <td>
195  * <a href="http://scip.zib.de/doc/examples/MIPSolver"><b>MIPSolver</b></a>
196  * </td>
197  * <td>
198  * A minimal implementation for using SCIP included into another source code
199  * </td>
200  * </tr>
201  * <tr>
202  * <td>
203  * <a href="http://scip.zib.de/doc/examples/Queen/scip_intro.pdf"><b>Queen</b></a>
204  * </td>
205  * <td>
206  * An example showing the use of SCIP as callable library.
207  * </td>
208  * </tr>
209  * </table>
210  *
211  *
212  * @section OTHERPLUGINS Other plugins
213  *
214  * <table>
215  * <tr>
216  * <td>
217  * <a href="http://scip.zib.de/doc/examples/Eventhdlr"><b>Eventhdlr</b></a>
218  * </td>
219  * <td>
220  * A small example illustrating the use of an event handler.
221  * </td>
222  * </tr>
223  * <tr>
224  * <td>
225  * <a href="http://scip.zib.de/doc/examples/Scheduler"><b>Scheduler</b></a>
226  * </td>
227  * <td>
228  * An example containing three readers and one primal heuristic for scheduling problems.
229  * </td>
230  * </tr>
231  * <tr>
232  * <td>
233  * <a href="http://scip.zib.de/doc/examples/GMI"><b>GMI</b></a>
234  * </td>
235  * <td>
236  * An example about Gomory mixed-integer cuts.
237  * </td>
238  * </tr>
239  * </table>
240  *
241  */
242 
243 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
244 /**@page CODE Coding style guidelines
245  *
246  * We follow the following coding style guidelines and recommend them for all developers.
247  *
248  * - Indentation is 3 spaces. No tabs anywhere in the code.
249  * - Always only one declaration in a line.
250  * - Braces are on a new line and not indented.
251  * - Spaces around all operators.
252  * - No spaces between control structure keywords like "if", "for", "while", "switch" and the corresponding brackets.
253  * - No spaces between a function name and the parenthesis in both the definition and function calls.
254  * - Use assert() to show preconditions for the parameters, invariants and postconditions.
255  * - All global functions start with "SCIP". In the usual naming scheme this is followed by the object and a method name
256  * like in SCIPlpAddRow(). Functions return TRUE or FALSE should be named like SCIPisFeasEQ().
257  * - Make all functions that are not used outside the module 'static'. Naming should start with a lower case letter.
258  * - Variable names should be all lower case.
259  * - For each structure there is a typedef with the name in all upper case.
260  * - Defines should be named all upper case.
261  * - Document functions, parameters, and variables in a doxygen conformed way.
262  *
263  * As an example, have a look at tree.c and see the examples below. We also provide settings for
264  * \ref XEMACS "(x)emacs" and \ref ECLIPSE "eclipse".
265  *
266  * @section CODEEXAMPLES Examples
267  *
268  * In this section we state a few examples illustrating the \SCIP code style.
269  *
270  * \code
271  * #ifdef __cplusplus
272  * extern "C" {
273  * #endif
274  *
275  * /** SCIP operation stage */
276  * enum SCIP_Stage
277  * {
278  * SCIP_STAGE_INIT = 0, /**< SCIP datastructures are initialized, no problem exists */
279  * SCIP_STAGE_PROBLEM = 1, /**< the problem is being created and modified */
280  * SCIP_STAGE_TRANSFORMING = 2, /**< the problem is being transformed into solving data space */
281  * SCIP_STAGE_TRANSFORMED = 3, /**< the problem was transformed into solving data space */
282  * SCIP_STAGE_PRESOLVING = 4, /**< the problem is being presolved */
283  * SCIP_STAGE_PRESOLVED = 5, /**< the problem was presolved */
284  * SCIP_STAGE_INITSOLVE = 6, /**< the solving process data is being initialized */
285  * SCIP_STAGE_SOLVING = 7, /**< the problem is being solved */
286  * SCIP_STAGE_SOLVED = 8, /**< the problem was solved */
287  * SCIP_STAGE_FREESOLVE = 9, /**< the solving process data is being freed */
288  * SCIP_STAGE_FREETRANS = 10 /**< the transformed problem is being freed */
289  * };
290  * typedef enum SCIP_Stage SCIP_STAGE;
291  *
292  * /** possible settings for enabling/disabling algorithms and other features */
293  * enum SCIP_Setting
294  * {
295  * SCIP_UNDEFINED = 0, /**< undefined setting */
296  * SCIP_DISABLED = 1, /**< feature is disabled */
297  * SCIP_AUTO = 2, /**< feature is set to automatic mode */
298  * SCIP_ENABLED = 3 /**< feature is enabled */
299  * };
300  * typedef enum SCIP_Setting SCIP_SETTING;
301  *
302  * #ifdef __cplusplus
303  * }
304  * #endif
305  * \endcode
306  *
307  * @section XEMACS Customize (x)emacs
308  *
309  * If you are using (x)emacs, you can use the following customization for the c++-mode. These settings satisfy the
310  * coding guidelines of \SCIP.
311  *
312  * \verbatim
313  (add-hook 'c++-mode-hook
314  (function
315  (lambda ()
316  ;; SCIP customizations for c-mode and c++-mode
317  (setq-default c-basic-offset 3)
318  (c-set-offset 'substatement-open 0)
319  (c-set-offset 'statement-case-open 0)
320  (c-set-offset 'brace-list-open '-)
321  (c-set-offset 'inextern-lang '0)
322  (c-set-offset 'arglist-intro '+)
323  (c-set-offset 'arglist-cont 0)
324  (c-set-offset 'arglist-cont-nonempty '+)
325  (c-set-offset 'arglist-close '+)
326  (set-variable 'fill-column 120)
327  ;; this will make sure spaces are used instead of tabs
328  (setq tab-width 8 indent-tabs-mode nil)
329  )))\endverbatim
330  *
331  * @section ECLIPSE Customize eclipse
332  *
333  *
334  * Eclipse user can use the profile below. This profile does not match the \SCIP coding guideline completely.
335  *
336  * \code
337  *
338  * <?xml version="1.0" encoding="UTF-8" standalone="no"?>
339  * <profiles version="1">
340  * <profile kind="CodeFormatterProfile" name="scip" version="1">
341  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_method_declaration" value="do not insert"/>
342  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_for" value="insert"/>
343  * <setting id="org.eclipse.cdt.core.formatter.insert_new_line_in_empty_block" value="insert"/>
344  * <setting id="org.eclipse.cdt.core.formatter.lineSplit" value="124"/>
345  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_base_types" value="do not insert"/>
346  * <setting id="org.eclipse.cdt.core.formatter.keep_else_statement_on_same_line" value="false"/>
347  * <setting id="org.eclipse.cdt.core.formatter.indent_switchstatements_compare_to_switch" value="false"/>
348  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_brace_in_array_initializer" value="insert"/>
349  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_method_declaration_parameters" value="do not insert"/>
350  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_if" value="insert"/>
351  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_exception_specification" value="do not insert"/>
352  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_parenthesized_expression" value="do not insert"/>
353  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_base_types" value="insert"/>
354  * <setting id="org.eclipse.cdt.core.formatter.indent_body_declarations_compare_to_access_specifier" value="true"/>
355  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_exception_specification" value="do not insert"/>
356  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_template_arguments" value="insert"/>
357  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_block" value="insert"/>
358  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_method_declaration" value="do not insert"/>
359  * <setting id="org.eclipse.cdt.core.formatter.use_tabs_only_for_leading_indentations" value="false"/>
360  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_labeled_statement" value="do not insert"/>
361  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_case" value="insert"/>
362  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_array_initializer" value="insert"/>
363  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_enum_declarations" value="insert"/>
364  * <setting id="org.eclipse.cdt.core.formatter.alignment_for_expressions_in_array_initializer" value="16"/>
365  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_declarator_list" value="insert"/>
366  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_bracket" value="do not insert"/>
367  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_for" value="insert"/>
368  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_prefix_operator" value="do not insert"/>
369  * <setting id="org.eclipse.cdt.core.formatter.tabulation.size" value="3"/>
370  * <setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_else_in_if_statement" value="insert"/>
371  * <setting id="org.eclipse.cdt.core.formatter.alignment_for_enumerator_list" value="48"/>
372  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_parenthesized_expression" value="do not insert"/>
373  * <setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_parens_in_method_declaration" value="do not insert"/>
374  * <setting id="org.eclipse.cdt.core.formatter.alignment_for_declarator_list" value="16"/>
375  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_switch" value="insert"/>
376  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_parenthesized_expression" value="do not insert"/>
377  * <setting id="org.eclipse.cdt.core.formatter.indent_empty_lines" value="false"/>
378  * <setting id="org.eclipse.cdt.core.formatter.indent_switchstatements_compare_to_cases" value="true"/>
379  * <setting id="org.eclipse.cdt.core.formatter.keep_empty_array_initializer_on_one_line" value="false"/>
380  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_method_declaration" value="insert"/>
381  * <setting id="org.eclipse.cdt.core.formatter.put_empty_statement_on_new_line" value="true"/>
382  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_switch" value="do not insert"/>
383  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_cast" value="do not insert"/>
384  * <setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_braces_in_array_initializer" value="do not insert"/>
385  * <setting id="org.eclipse.cdt.core.formatter.brace_position_for_method_declaration" value="next_line"/>
386  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_while" value="insert"/>
387  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_question_in_conditional" value="insert"/>
388  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_semicolon" value="do not insert"/>
389  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_angle_bracket_in_template_arguments" value="insert"/>
390  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_base_clause" value="do not insert"/>
391  * <setting id="org.eclipse.cdt.core.formatter.indent_breaks_compare_to_cases" value="true"/>
392  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_unary_operator" value="do not insert"/>
393  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_declarator_list" value="do not insert"/>
394  * <setting id="org.eclipse.cdt.core.formatter.alignment_for_arguments_in_method_invocation" value="16"/>
395  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_while" value="do not insert"/>
396  * <setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_brackets" value="do not insert"/>
397  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_bracket" value="do not insert"/>
398  * <setting id="org.eclipse.cdt.core.formatter.alignment_for_parameters_in_method_declaration" value="48"/>
399  * <setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_closing_brace_in_array_initializer" value="do not insert"/>
400  * <setting id="org.eclipse.cdt.core.formatter.number_of_empty_lines_to_preserve" value="1"/>
401  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_method_invocation" value="do not insert"/>
402  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_brace_in_array_initializer" value="insert"/>
403  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_semicolon_in_for" value="do not insert"/>
404  * <setting id="org.eclipse.cdt.core.formatter.brace_position_for_block" value="next_line"/>
405  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_conditional" value="insert"/>
406  * <setting id="org.eclipse.cdt.core.formatter.brace_position_for_type_declaration" value="next_line"/>
407  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_assignment_operator" value="insert"/>
408  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_angle_bracket_in_template_arguments" value="do not insert"/>
409  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_expression_list" value="do not insert"/>
410  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_angle_bracket_in_template_parameters" value="do not insert"/>
411  * <setting id="org.eclipse.cdt.core.formatter.continuation_indentation" value="1"/>
412  * <setting id="org.eclipse.cdt.core.formatter.alignment_for_expression_list" value="0"/>
413  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_method_declaration" value="do not insert"/>
414  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_template_parameters" value="do not insert"/>
415  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_default" value="do not insert"/>
416  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_binary_operator" value="insert"/>
417  * <setting id="org.eclipse.cdt.core.formatter.alignment_for_conditional_expression" value="16"/>
418  * <setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_parens_in_method_invocation" value="do not insert"/>
419  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_array_initializer" value="do not insert"/>
420  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_if" value="insert"/>
421  * <setting id="org.eclipse.cdt.core.formatter.format_guardian_clause_on_one_line" value="false"/>
422  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_cast" value="do not insert"/>
423  * <setting id="org.eclipse.cdt.core.formatter.indent_access_specifier_compare_to_type_header" value="false"/>
424  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_type_declaration" value="insert"/>
425  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_labeled_statement" value="insert"/>
426  * <setting id="org.eclipse.cdt.core.formatter.continuation_indentation_for_array_initializer" value="1"/>
427  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_method_declaration_parameters" value="insert"/>
428  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_semicolon_in_for" value="insert"/>
429  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_method_invocation" value="do not insert"/>
430  * <setting id="org.eclipse.cdt.core.formatter.indent_body_declarations_compare_to_namespace_header" value="false"/>
431  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_brace_in_block" value="insert"/>
432  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_assignment_operator" value="insert"/>
433  * <setting id="org.eclipse.cdt.core.formatter.alignment_for_compact_if" value="0"/>
434  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_array_initializer" value="insert"/>
435  * <setting id="org.eclipse.cdt.core.formatter.insert_new_line_at_end_of_file_if_missing" value="do not insert"/>
436  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_template_parameters" value="insert"/>
437  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_expression_list" value="insert"/>
438  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_question_in_conditional" value="insert"/>
439  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_exception_specification" value="insert"/>
440  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_binary_operator" value="insert"/>
441  * <setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_identifier_in_function_declaration" value="do not insert"/>
442  * <setting id="org.eclipse.cdt.core.formatter.alignment_for_base_clause_in_type_declaration" value="80"/>
443  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_method_declaration_throws" value="do not insert"/>
444  * <setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_parens_in_exception_specification" value="do not insert"/>
445  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_method_invocation_arguments" value="do not insert"/>
446  * <setting id="org.eclipse.cdt.core.formatter.indent_declaration_compare_to_template_header" value="false"/>
447  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_unary_operator" value="do not insert"/>
448  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_switch" value="do not insert"/>
449  * <setting id="org.eclipse.cdt.core.formatter.indent_statements_compare_to_body" value="true"/>
450  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_method_declaration_throws" value="insert"/>
451  * <setting id="org.eclipse.cdt.core.formatter.indent_statements_compare_to_block" value="true"/>
452  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_template_arguments" value="do not insert"/>
453  * <setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_catch_in_try_statement" value="insert"/>
454  * <setting id="org.eclipse.cdt.core.formatter.alignment_for_throws_clause_in_method_declaration" value="48"/>
455  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_method_invocation" value="do not insert"/>
456  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_paren_in_cast" value="do not insert"/>
457  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_catch" value="insert"/>
458  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_angle_bracket_in_template_parameters" value="do not insert"/>
459  * <setting id="org.eclipse.cdt.core.formatter.tabulation.char" value="space"/>
460  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_angle_bracket_in_template_parameters" value="do not insert"/>
461  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_while" value="insert"/>
462  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_method_invocation_arguments" value="insert"/>
463  * <setting id="org.eclipse.cdt.core.formatter.brace_position_for_block_in_case" value="next_line"/>
464  * <setting id="org.eclipse.cdt.core.formatter.compact_else_if" value="true"/>
465  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_postfix_operator" value="do not insert"/>
466  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_base_clause" value="insert"/>
467  * <setting id="org.eclipse.cdt.core.formatter.insert_new_line_after_template_declaration" value="do not insert"/>
468  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_catch" value="insert"/>
469  * <setting id="org.eclipse.cdt.core.formatter.keep_then_statement_on_same_line" value="false"/>
470  * <setting id="org.eclipse.cdt.core.formatter.brace_position_for_switch" value="next_line"/>
471  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_if" value="do not insert"/>
472  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_switch" value="insert"/>
473  * <setting id="org.eclipse.cdt.core.formatter.keep_imple_if_on_one_line" value="false"/>
474  * <setting id="org.eclipse.cdt.core.formatter.insert_new_line_after_opening_brace_in_array_initializer" value="do not insert"/>
475  * <setting id="org.eclipse.cdt.core.formatter.indentation.size" value="3"/>
476  * <setting id="org.eclipse.cdt.core.formatter.brace_position_for_namespace_declaration" value="end_of_line"/>
477  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_conditional" value="insert"/>
478  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_enum_declarations" value="do not insert"/>
479  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_prefix_operator" value="do not insert"/>
480  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_angle_bracket_in_template_arguments" value="do not insert"/>
481  * <setting id="org.eclipse.cdt.core.formatter.brace_position_for_array_initializer" value="end_of_line"/>
482  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_case" value="do not insert"/>
483  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_catch" value="do not insert"/>
484  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_namespace_declaration" value="insert"/>
485  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_postfix_operator" value="do not insert"/>
486  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_bracket" value="do not insert"/>
487  * <setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_while_in_do_statement" value="insert"/>
488  * <setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_for" value="do not insert"/>
489  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_angle_bracket_in_template_parameters" value="insert"/>
490  * <setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_angle_bracket_in_template_arguments" value="do not insert"/>
491  * </profile>
492  * </profiles>
493  * \endcode
494  */
495 
496 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
497 /**@page MAKE Makefiles / Installation information
498  *
499  *
500  * In most cases (LINUX and MAC) it is quite easy to compile and install SCIP. Therefore, reading the section
501  * \ref BRIEFINSTALL "Brief installation description" should usually be enough. If this is not the case you find
502  * \ref DETAILEDINSTALL "Detailed installation description" below as well as \ref EXAMPLE1 "Examples".
503 *
504  * @section BRIEFINSTALL Brief installation description
505  *
506  * The easiest way to install SCIP is to use the SCIP Optimization Suite which contains SCIP, SoPlex, and ZIMPL. For
507  * that we refer to the INSTALL file of the SCIP Optimization Suite (main advantage: there is no need
508  * to specify any directories, the compiling process is fully automated).
509  *
510  * Compiling SCIP directly can be done as follows:
511  *
512  * -# unpack the tarball <code>tar xvf scip-x.y.z.tgz</code>
513  * -# change to the directory <code>cd scip-x.y.z</code>
514  * -# start compiling SCIP by typing <code>make</code>
515  * -# (optional) install the header, libraries, and binary <code>make install INSTALLDIR="/usr/local/</code>
516  *
517  * During your first compilation you will be asked for some soft-link targets,
518  * depending on the LP solver you want to use. Usually, SCIP needs the
519  * following information
520  * -# the directory where the include files of the LP solver lie
521  * -# the library file(s) "lib*.a" or/and "lib*.so"
522  *
523  * Besides that, SCIP needs some soft-link targets, for ZIMPL
524  * -# the directory where the include files of ZIMPL lie
525  * -# the library file(s) "lib*.a" or/and "lib*.so"
526  *
527  * You will need either the .a or the .so files and can skip the others by
528  * just pressing return.
529  *
530  * The most common compiling issue is that some libraries are missing
531  * on your system or that they are outdated. SCIP per default requires
532  * zlib, gmp and readline. Try compiling with: <code> make ZLIB=false
533  * READLINE=false ZIMPL=false</code> or, better, install them. Note
534  * that under Linux-based systems, you need to install the
535  * developer-versions of gmp/zlib/readline, in order to also have the
536  * header-files available.
537  *
538  @section DETAILEDINSTALL Detailed installation description
539  *
540  * In this section we describe the use, and a few features, of the SCIP Makefile. We also give two examples for how to install
541  * SCIP. The \ref EXAMPLE1 "first example" illustrates the default installation. This means, with SoPleX and ZIMPL. The
542  * \ref EXAMPLE2 "second example" shows how to get CPLEX linked to SCIP without ZIMPL. This is followed by a section which
543  * gives some hints on what to do if the \ref COMPILERPROBLEMS "compilation throws an error". We give some comments on
544  * how to install SCIP under \ref WINDOWS "WINDOWS" and show \ref RUN "how to start SCIP".
545  *
546  * If you experience any problems during the installation, you will find help in the \ref INSTALL "INSTALL" file.
547  *
548  * SCIP contains a makefile system, which allows the individual setting of several parameters. For
549  * instance, the following settings are supported:
550  *
551  * - <code>OPT=<dbg|opt|opt-gccold></code> Here <code>dbg</code> turns on the debug mode of SCIP. This enables asserts
552  * and avoids macros for several function in order to ease debugging. The default is <code>opt</code>, which enables
553  * the optimized mode. The third option <code>opt-gccold</code> will work with older GCC compilers before version
554  * 4.2. We recommend using newer GCC versions.
555  *
556  * - <code>LPS=<clp|cpx|grb|msk|qso|spx|xprs|none></code> This determines the LP-solver, which should have been
557  * installed separately from SCIP. The options are the following:
558  * - <code>clp</code>: COIN-OR Clp LP-solver
559  * - <code>cpx</code>: CPLEX LP-solver
560  * - <code>grb</code>: Gurobi LP-solver (interface is in beta stage)
561  * - <code>msk</code>: Mosek LP-solver
562  * - <code>qso</code>: QSopt LP-solver
563  * - <code>spx</code>: SoPlex LP-solver (default)
564  * - <code>xprs</code>: XPress LP-solver
565  * - <code>none</code>: no LP-solver (you should set the parameter <lp/solvefreq> to <-1> to avoid solving LPs)
566  *
567  * - <code>LPSOPT=<dbg|opt|opt-gccold></code> Chooses the debug or optimized version (or old GCC optimized) version of
568  * the LP-solver. (currently only available for SoPlex and CLP)
569  *
570  * - <code>ZIMPL=<true|false></code> Turns direct support of ZIMPL in SCIP on (default) or off, respectively.
571  * - <code>ZIMPLOPT=<dbg|opt|opt-gccold></code> Chooses the debug or optimized (default) (or old GCC optimized)
572  * version of ZIMPL, if ZIMPL support is enabled. \n
573  * If the ZIMPL-support is disabled, the GMP-library is no longer needed for SCIP and therefore not linked to SCIP.
574  *
575  * - <code>READLINE=<true|false></code> Turns support via the readline library on (default) or off, respectively.
576  *
577  * - <code>IPOPT=<true|false></code> to enable or disable (default) IPOPT interface (needs IPOPT)
578  *
579  * - <code>EXPRINT=<cppad|none></code> to use CppAD as expressions interpreter (default) or no expressions interpreter
580  *
581  * - <code>GAMS=<true|false></code> to enable or disable (default) reading functionality in GAMS reader (needs GAMS)
582  *
583  * There are additional parameters for Linux/Gnu compilers:
584  *
585  * - <code>NOBLKBUFMEM=<true></code> turns off the internal SCIP block and buffer memory. This way the code can be checked by valgrind or
586  * similar tools. (The individual options <code>NOBLKMEM=<true></code> and <code>NOBUFMEM=<true></code> to turn off the SCIP block and
587  * buffer memory, respectively, exist as well).
588  *
589  * - <code>SHARED=<true></code> generates a shared object of the SCIP libraries. (The binary uses these shared
590  * libraries as well.)
591  * - <code>OPT=prf</code> generates a profiling version of SCIP providing a detailed statistic of the time usage of
592  * every method of SCIP.
593  *
594  * You can use other compilers - depending on the system:
595  *
596  * - <code>COMP=intel</code> Uses of the Intel compiler which is only available with the main optimization flags
597  * <code>OPT=<dbg|opt></code>. (Default is gcc/g++ represented through <code>COMP=gnu</code>.)
598  *
599  * There is the possibility to watch the compilation more precisely:
600  *
601  * - <code>VERBOSE=<true|false></code> Turns the extensive output on or off (default).
602  *
603  * The SCIP makefile supports several targets (used via <code>make ... "target"</code>):
604  *
605  * - <code>links</code> Reconfigures the links in the "lib" directory.
606  * - <code>doc</code> Creates documentation in the "doc" directory.
607  * - <code>clean</code> Removes all object files.
608  * - <code>depend</code> Creates dependencies files. This is only needed if you add files to SCIP.
609  * - <code>check</code> Runs the check script, see \ref TEST.
610  *
611  * The SCIP makefiles are structured as follows.
612  *
613  * - <code>Makefile</code> This is the basic makefile in the SCIP root directory. It loads
614  * additional makefile information depending on the parameters set.
615  * - <code>make/make.project</code> This file contains definitions that are useful for all codes
616  * that use SCIP, for instance, the examples.
617  * - <code>make.<sys>.<machine>.<compiler>.<dbg|opt|prf|opt-gccold></code> These file contain system/compiler specific
618  * definitions. If you have an unsupported compiler, you can copy one of these and modify it
619  * accordingly.
620  *
621  * If your platform or compiler is not supported by SCIP you might try and copy one of the existing
622  * makefiles in the <code>make</code> directory and modify it. If you succeed, we are always
623  * interested in including more Makefiles into the system.
624  *
625  *
626  * @section EXAMPLE1 Example 1 (defaults: SoPlex, with ZIMPL support):
627  *
628  * Typing <code>make</code> uses SoPlex as LP solver and includes support for the modeling language ZIMPL. You will be asked the
629  * following questions on the first call to "make" (example answers are already given):
630  *
631  * \verbatim
632  > make
633  make[1]: Entering directory `scip-1.2'
634 
635  - Current settings: LPS=spx OSTYPE=linux ARCH=x86_64 COMP=gnu SUFFIX= ZIMPL=true ZIMPLOPT=opt IPOPT=false IPOPTOPT=opt
636 
637  * SCIP needs some softlinks to external programs, in particular, LP-solvers.
638  * Please insert the paths to the corresponding directories/libraries below.
639  * The links will be installed in the 'lib' directory.
640  * For more information and if you experience problems see the INSTALL file.
641 
642  -> "spxinc" is the path to the SoPlex "src" directory, e.g., "../../soplex/src".
643  -> "libsoplex.*" is the path to the SoPlex library, e.g., "../../soplex/lib/libsoplex.linux.x86.gnu.opt.a"
644  -> "zimplinc" is a directory containing the path to the ZIMPL "src" directory, e.g., "../../zimpl/src".
645  -> "libzimpl.*" is the path to the ZIMPL library, e.g., "../../zimpl/lib/libzimpl.linux.x86.gnu.opt.a"
646 
647  - preparing missing soft-link "lib/spxinc":
648  > Enter soft-link target file or directory for "lib/spxinc" (return if not needed):
649  > ../../soplex/src/
650  -> creating softlink "lib/spxinc" -> "../../soplex/src"
651 
652 
653  - preparing missing soft-link "lib/libsoplex.linux.x86_64.gnu.opt.a":
654  > Enter soft-link target file or directory for "lib/libsoplex.linux.x86_64.gnu.opt.a" (return if not needed):
655  > ../../soplex/lib/libsoplex.linux.x86_64.gnu.opt.a
656  -> creating softlink "lib/libsoplex.linux.x86_64.gnu.opt.a" -> "../../soplex/lib/libsoplex.linux.x86_64.gnu.opt.a"
657 
658 
659  - preparing missing soft-link "lib/libsoplex.linux.x86_64.gnu.opt.so":
660  * this soft-link is not necessarily needed since "lib/libsoplex.linux.x86_64.gnu.opt.a" already exists - press return to skip
661  > Enter soft-link target file or directory for "lib/libsoplex.linux.x86_64.gnu.opt.so" (return if not needed):
662  >
663  * skipped creation of softlink "lib/libsoplex.linux.x86_64.gnu.opt.so". Call "make links" if needed later.
664 
665 
666  - preparing missing soft-link "lib/zimplinc/zimpl":
667  > Enter soft-link target file or directory for "lib/zimplinc/zimpl" (return if not needed):
668  ../../zimpl/src/
669  creating softlink "lib/zimplinc/zimpl" -> "../../zimpl/src"
670 
671 
672  - preparing missing soft-link "lib/libzimpl.linux.x86_64.gnu.opt.a":
673  > Enter soft-link target file or directory for "lib/libzimpl.linux.x86_64.gnu.opt.a" (return if not needed):
674  > ../../zimpl/lib/libzimpl.linux.x86_64.gnu.opt.a
675  -> creating softlink "lib/libzimpl.linux.x86_64.gnu.opt.a" -> "../../zimpl/lib/libzimpl.linux.x86_64.gnu.opt.a"
676 
677 
678  - preparing missing soft-link "lib/libzimpl.linux.x86_64.gnu.opt.so":
679  * this soft-link is not necessarily needed since "lib/libzimpl.linux.x86_64.gnu.opt.a" already exists - press return to skip
680  > Enter soft-link target file or directory for "lib/libzimpl.linux.x86_64.gnu.opt.so" (return if not needed):
681  >
682  * skipped creation of softlink "lib/libzimpl.linux.x86_64.gnu.opt.so". Call "make links" if needed later.
683 
684  ...
685 
686  -> generating library lib/libobjscip-1.2.0.linux.x86_64.gnu.opt.a
687  -> generating library lib/liblpispx-1.2.0.linux.x86_64.gnu.opt.a
688  -> generating library lib/libscip-1.2.0.linux.x86_64.gnu.opt.a
689  -> linking bin/scip-1.2.0.linux.x86_64.gnu.opt.spx
690 
691  \endverbatim
692  *
693  * @section EXAMPLE2 Example 2 (CPLEX, with no ZIMPL support):
694  *
695  * Typing <code>make LPS=cpx ZIMPL=false</code> uses CPLEX as LP solver. You will be asked the following questions on
696  * the first call to "make" (example answers are already given):
697  *
698  * \verbatim
699  > make LPS=cpx ZIMPL=false
700  make[1]: Entering directory `scip-1.2'
701 
702  - Current settings: LPS=cpx OSTYPE=linux ARCH=x86_64 COMP=gnu SUFFIX= ZIMPL=false ZIMPLOPT=opt IPOPT=false IPOPTOPT=opt
703 
704  * SCIP needs some softlinks to external programs, in particular, LP-solvers.
705  * Please insert the paths to the corresponding directories/libraries below.
706  * The links will be installed in the 'lib' directory.
707  * For more information and if you experience problems see the INSTALL file.
708 
709  -> "cpxinc" is the path to the CPLEX "include" directory, e.g., "<CPLEX-path>/include/ilcplex".
710  -> "libcplex.*" is the path to the CPLEX library, e.g., "<CPLEX-path>/lib/x86_rhel4.0_3.4/static_pic/libcplex.a"
711 
712  - preparing missing soft-link "lib/cpxinc":
713  > Enter soft-link target file or directory for "lib/cpxinc" (return if not needed):
714  > ../../cplex121/include
715  -> creating softlink "lib/cpxinc" -> "../../cplex121/include"
716 
717 
718  - preparing missing soft-link "lib/libcplex.linux.x86_64.gnu.a":
719  > Enter soft-link target file or directory for "lib/libcplex.linux.x86_64.gnu.a" (return if not needed):
720  > ../../cplex121/lib/x86-64_sles9.0_3.3/static_pic/libcplex.a
721  -> creating softlink "lib/libcplex.linux.x86_64.gnu.a" -> "../../../../adm_cple/cplex121/lib/x86-64_sles9.0_3.3/static_pic/libcplex.a"
722 
723 
724  - preparing missing soft-link "lib/libcplex.linux.x86_64.gnu.so":
725  > Enter soft-link target file or directory for "lib/libcplex.linux.x86_64.gnu.so" (return if not needed):
726  >
727  * skipped creation of softlink "lib/libcplex.linux.x86_64.gnu.so". Call "make links" if needed later.
728 
729  ...
730 
731  -> generating library lib/libobjscip-1.2.0.linux.x86_64.gnu.opt.a
732  -> generating library lib/liblpicpx-1.2.0.linux.x86_64.gnu.opt.a
733  -> generating library lib/libscip-1.2.0.linux.x86_64.gnu.opt.a
734  -> linking bin/scip-1.2.0.linux.x86_64.gnu.opt.cpx
735 
736  \endverbatim
737  *
738  * @section COMPILERPROBLEMS Compilation problems:
739  *
740  * - If the soft-link query script does not work on your machine, read step 2 in the \ref INSTALL "INSTALL" file for
741  * instructions on manually creating the soft-links.
742  *
743  * - If you get an error message of the type\n
744  * <code>make: *** No rule to make target `lib/???', needed by `obj/O.linux.x86.gnu.opt/lib/scip/???.o'. Stop.</code>\n
745  * the corresponding soft-link was not created or points to a wrong location. Check the soft-link targets in the "lib/"
746  * subdirectory. Try to delete all soft-links from the "lib/" directory\n and call "make links" to generate them
747  * again. If this still fails, read step 2 for instructions on manually\n creating the soft-links.
748  *
749  * - If you get an error message of the type\n
750  * <code>make: *** No rule to make target `make/make.?.?.?.?.?'. Stop.</code>,\n
751  * the corresponding machine dependent makefile for your architecture and compiler is missing.\n Create one of the given
752  * name in the "make/" subdirectory. You may take\n "make/make.linux.x86.gnu.opt" or any other file in the make
753  * subdirectory as example.\n
754  *
755  * - The readline library seems to differ slightly on different OS distributions. Some versions do
756  * not support the <code>remove_history()</code> call. In this case, you have to either add
757  * <code>-DNO_REMOVE_HISTORY</code> to the FLAGS in the appropriate "make/make.*" file, or to
758  * compile with <code>make USRFLAGS=-DNO_REMOVE_HISTORY</code>. Make sure, the file
759  * "src/scip/dialog.c" is recompiled. If this doesn't work either, disable the readline library
760  * with <code>make READLINE=false</code>.
761  *
762  * - On some systems, the <code>sigaction()</code> method is not available. In this case, you have
763  * to either add <code>-DNO_SIGACTION</code> to the FLAGS in the appropriate "make/make.*" file, or
764  * to compile with <code>make USRFLAGS=-DNO_SIGACTION</code>. Make sure, the file
765  * "src/scip/interrupt.c" is recompiled.
766  *
767  * - On some systems, the <code>rand_r()</code> method is not available. In this case, you have to either add
768  * <code>-DNO_RAND_R</code> to the FLAGS in the appropriate "make/make.*" file, or to compile with
769  * <code>make USRFLAGS=-DNO_RAND_R</code>. Make sure, the file "src/scip/misc.c" is recompiled.
770  *
771  * - On some systems, the <code>strtok_r()</code> method is not available. In this case, you have
772  * to either add <code>-DNO_STRTOK_R</code> to the FLAGS in the appropriate make/make.* file, or to
773  * compile with <code>make USRFLAGS=-DNO_STRTOK_R</code>. Make sure, the file "src/scip/misc.c" is
774  * recompiled.
775  *
776  * - On some systems, the <code>strerror_r()</code> method is not available. In this case, you have
777  * to either add <code>-DNO_STRERROR_R</code> to the FLAGS in the appropriate "make/make.*" file, or
778  * to compile with <code>make USRFLAGS=-DNO_STRERROR_R</code>. Make sure, the file
779  * "src/scip/misc.c" is recompiled.
780  *
781  * - On some systems, the option [-e] is not available for the read command. You have to compile with READ=read.
782  *
783  * - If you encounter other compiler or linker errors, you should recompile with <code>make
784  * VERBOSE=true ...</code> in order to get the full compiler invocation. This might help to fix the
785  * corresponding machine dependent makefile in the make subdirectory.
786  *
787  * @section WINDOWS Remarks on Installing under Windows using MinGW
788  *
789  * To build your own windows binaries under windows we recommend using the MinGW-Compiler with MSYS
790  * from <a href="http://www.mingw.org">www.mingw.org</a> .
791  *
792  * First install MSYS, then MinGW to the mingw folder inside the msys folder.
793  * Now you need to install the following packages to the mingw folder:
794  * - zlib (or use ZLIB=false)
795  * - pcre (here suffices the pcre7.0-lib.zip (or equivalent) to be extracted into the mingw-folder)
796  *
797  * After calling <code>make clean</code> in the ZIMPL folder you will also need flex and bison to
798  * remake ZIMPL. We recommend NOT to use <code>"make clean"</code> inside the ZIMPL-folder if you do
799  * not have these packages installed.
800  *
801  * You can download these additional packages from <a href="http://gnuwin32.sourceforge.net/packages.html">here</a>
802  * or compile the source on your own from their homepages.
803  *
804  * Second you need to copy the file <code>sh.exe</code> to <code>bash.exe</code> otherwise various
805  * scripts (including makefiles) will not work. Normally <code>unistd.h</code> covers also the
806  * getopt-options, but for mingw you need to add the entry <code>\#include <getopt.h></code> into
807  * "/mingw/include/unistd.h" after the other include-entries (if not present).
808  *
809  * Finally, there is one package you need to compile if you want to use ZIMPL and ZIMPL-support in
810  * SCIP (otherwise use <code>ZIMPL=false</code> as parameter with the make-call): the
811  * <code>gmplib</code> from <a href="http://www.gmplib.org">gmplib.org</a>. The command
812  * <code>./configure --prefix=/mingw ; make ; make install</code> should succeed without problems
813  * and installs the gmplib to the mingw folder.
814  *
815  * Now <code>make READLINE=false</code> should be compiling without errors. Please note that we
816  * do NOT support creating the doxygen documentation and readline-usage under windows.
817  *
818  *
819  * @section RUN How to run SCIP after successfully compiling SCIP
820  *
821  * To run the program, enter <code>bin/scip</code> for the last compiled version. If you have more than one compiled
822  * binary (i. e., one in debug and one in optimized mode) and wish to specify the binary, type
823  * <code>bin/scip.\$(OSTYPE).\$(ARCH).\$(COMP).\$(OPT).\$(LPS)</code>
824  * (e.g. <code>bin/scip.linux.x86_64.gnu.opt.spx</code>).
825  *
826  */
827 
828 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
829 /**@page START How to start a new project
830  *
831  * Once you succeeded installing SCIP together with an LP-solver on your system,
832  * you have a powerful tool for solving MIPs, MIQCPs,
833  * MINLPs, etc... at hand. SCIP can also be customized to the type of problems you
834  * are working on by additional plugins.
835  * Instructions on how to write a new plugin and include it in SCIP can be found in the corresponding
836  * \ref HOWTOADD "How to add ... pages".
837  *
838  * SCIP can also be used for writing your own branch-and-cut or branch-and-cut-and-price code. SCIP already
839  * provides a number of existing code examples which we suggest as both reference and starting point
840  * for these kinds of projects.
841  * Below, you find some hints of how to start such a project.
842  *
843  * - The example should be chosen
844  * depending on the programming language (<b>C</b> or <b>C++</b>) and the purpose
845  * (<b>branch-and-cut</b> or <b>branch-and-cut-and-price</b>) of your project.
846  * <br>
847  * We suggest the use one of the following examples:
848  * - The <a href="http://scip.zib.de/doc/examples/VRP"><b>VRP</b></a>-example is a <b>branch-and-cut-and-price</b> (column generation)-code
849  * in <b>C++</b>.
850  * - The <a href="http://scip.zib.de/doc/examples/Coloring"><b>Coloring</b></a>
851  * and the <a href="http://scip.zib.de/doc/examples/Binpacking"><b>Binpacking</b></a>-example are
852  * <b>branch-and-cut-and-price</b> (column generation)-codes in <b>C</b>.
853  * - The <a href="http://scip.zib.de/doc/examples/TSP"><b>TSP</b></a>-example
854  * is a <b>branch-and-cut</b>-code in <b>C++</b>.
855  * - The <a href="http://scip.zib.de/doc/examples/LOP"><b>LOP</b></a>-example
856  * is a <b>branch-and-cut</b>-code in <b>C</b>.
857  * .
858  * - Copy one of the examples in the <code>examples</code> directory (in the SCIP root
859  * directory). For instance, type
860  * \verbatim
861  > cp -r examples/Coloring/ ../SCIPProject/ ; cd ../SCIPProject
862  \endverbatim
863  * from the SCIP root directory for copying the content of the <code>Coloring</code>-example into a fresh
864  * directory named SCIPProject in the parent directory of the SCIP root directory and jumping to
865  * the new SCIPProject directory rightafter.
866  * - Open the <code>Makefile</code> via
867  * \verbatim
868  > kate Makefile
869  \endverbatim
870  * and edit the following variables at the top to have a compilable code:
871  *
872  * - specify a correct path to the SCIP root (<code>SCIPDIR</code>)
873  * - rename the targets name (<code>MAINNAME</code>)
874  * - adjust the source file names (<code>MAINOBJ</code>).
875  * .
876  * - Once you have edited the makefile, you can use all the flags that can be used in SCIP to
877  * compile your code, see \ref MAKE.
878  * Note that you need to update the dependency files before compiling your project via <code>make depend</code>.
879  *
880  *
881  *
882  *
883  */
884 
885 
886 /**@page SHELL Tutorial: the interactive shell
887  *
888  * If are using SCIP as a black box solver, here you will find some tips and tricks what you can do.
889  *
890  * First of all, we need a SCIP binary and an example problem file to work with. Therefore, you can either download the
891  * SCIP standard distribution (which includes problem files) and compile it on your own or you can download a
892  * precompiled binary and an example problem separately. SCIP can read files in LP, MPS, ZPL, WBO, FZN, PIP, OSiL, and other formats (see \ref FILEREADERS).
893  *
894  * If you want to download the source code of the SCIP standard distribution, we recommend to go to the <a
895  * href="http://scip.zib.de/#download">SCIP download section</a>, download the latest release (version 3.0 as
896  * of this writing), inflate the tarball (e.g., with "tar xzf scipoptsuite-[version].tgz"), and follow the instructions
897  * in the INSTALL file. The instance stein27, which will serve as an example in this tutorial, can be found under
898  * scipoptsuite-[version]/scip-[version]/check/instances/MIP/stein27.mps.
899  *
900  * If you want to download a precompiled binary, go to the <a href="http://scip.zib.de/#download">SCIP download
901  * section</a> and download an appropriate binary for your operating system. To follow this tutorial, we recommend downloading the instance
902  * <a href="http://miplib.zib.de/miplib3/miplib3/stein27.mps.gz">stein27</a> from
903  * the <a href="http://miplib.zib.de/miplib3/miplib.html">MIPLIB 3.0</a> homepage.
904  *
905  * Now start your binary, without any arguments. This opens the interactive shell, which should look somehow like this:
906  *
907  * \code
908  * SCIP version 2.0.1 [precision: 8 byte] [memory: block] [mode: optimized] [LP solver: SoPlex 1.5.0]
909  * Copyright (c) 2002-2014 Konrad-Zuse-Zentrum fuer Informationstechnik Berlin (ZIB)
910  *
911  * External codes:
912  * SoPlex 1.5.0 Linear Programming Solver developed at Zuse Institute Berlin (soplex.zib.de)
913  * ZIMPL 3.1.0 Zuse Institute Mathematical Programming Language developed by T. Koch (zimpl.zib.de)
914  *
915  * user parameter file <scip.set> not found - using default parameters
916  *
917  * SCIP>
918  * \endcode
919  *
920  * First of all "help" shows you a list of all available shell commands. Brackets indicate a submenu with further options.
921  * \code
922  * SCIP> help
923 
924  * <display> display information
925  * <set> load/save/change parameters
926  * ...
927  * read read a problem
928  * \endcode
929  *
930  * Okay, let's solve some MIPs... use "read <path/to/file>" to parse a problem file, "optimize" to solve it and "display
931  * solution" to show the nonzero variables of the best found solution.
932 
933  * \code
934  * SCIP> read check/instances/MIP/stein27.mps
935  * original problem has 27 variables (27 bin, 0 int, 0 impl, 0 cont) and 118 constraints
936  * SCIP> optimize
937  *
938  * feasible solution found by trivial heuristic, objective value 2.700000e+01
939  * presolving:
940  * (round 1) 0 del vars, 0 del conss, 0 chg bounds, 0 chg sides, 0 chg coeffs, 118 upgd conss, 0 impls, 0 clqs
941  * presolving (2 rounds):
942  * 0 deleted vars, 0 deleted constraints, 0 tightened bounds, 0 added holes, 0 changed sides, 0 changed coefficients
943  * 0 implications, 0 cliques
944  * presolved problem has 27 variables (27 bin, 0 int, 0 impl, 0 cont) and 118 constraints
945  * 1 constraints of type <knapsack>
946  * 117 constraints of type <logicor>
947  * transformed objective value is always integral (scale: 1)
948  * Presolving Time: 0.00
949  *
950  * time | node | left |LP iter|LP it/n| mem |mdpt |frac |vars |cons |cols |rows |cuts |confs|strbr| dualbound | primalbound | gap
951  * t 0.0s| 1 | 0 | 34 | - | 337k| 0 | 21 | 27 | 118 | 27 | 118 | 0 | 0 | 0 | 1.300000e+01 | 2.700000e+01 | 107.69%
952  * R 0.0s| 1 | 0 | 34 | - | 338k| 0 | 21 | 27 | 118 | 27 | 118 | 0 | 0 | 0 | 1.300000e+01 | 2.600000e+01 | 100.00%
953  * s 0.0s| 1 | 0 | 34 | - | 339k| 0 | 21 | 27 | 118 | 27 | 118 | 0 | 0 | 0 | 1.300000e+01 | 2.500000e+01 | 92.31%
954  * 0.0s| 1 | 0 | 44 | - | 392k| 0 | 21 | 27 | 118 | 27 | 120 | 2 | 0 | 0 | 1.300000e+01 | 2.500000e+01 | 92.31%
955  * b 0.0s| 1 | 0 | 44 | - | 393k| 0 | 21 | 27 | 118 | 27 | 120 | 2 | 0 | 0 | 1.300000e+01 | 1.900000e+01 | 46.15%
956  * ...
957  * 0.1s| 1 | 2 | 107 | - | 920k| 0 | 24 | 27 | 118 | 27 | 131 | 13 | 0 | 24 | 1.300000e+01 | 1.900000e+01 | 46.15%
958  * R 0.1s| 14 | 10 | 203 | 7.4 | 935k| 13 | - | 27 | 118 | 27 | 124 | 13 | 0 | 164 | 1.300000e+01 | 1.800000e+01 | 38.46%
959  * 0.1s| 100 | 54 | 688 | 5.9 | 994k| 13 | 20 | 27 | 118 | 27 | 124 | 13 | 0 | 206 | 1.300000e+01 | 1.800000e+01 | 38.46%
960  * 0.1s| 200 | 86 | 1195 | 5.5 |1012k| 13 | - | 27 | 119 | 27 | 124 | 13 | 1 | 207 | 1.300000e+01 | 1.800000e+01 | 38.46%
961  * time | node | left |LP iter|LP it/n| mem |mdpt |frac |vars |cons |cols |rows |cuts |confs|strbr| dualbound | primalbound | gap
962  * 0.2s| 300 | 106 | 1686 | 5.3 |1024k| 13 | - | 27 | 119 | 27 | 124 | 13 | 1 | 207 | 1.350000e+01 | 1.800000e+01 | 33.33%
963  * ...
964  * 0.7s| 4100 | 50 | 18328 | 4.4 |1033k| 16 | 8 | 27 | 119 | 27 | 124 | 13 | 15 | 207 | 1.650000e+01 | 1.800000e+01 | 9.09%
965  *
966  * SCIP Status : problem is solved [optimal solution found]
967  * Solving Time (sec) : 0.73
968  * Solving Nodes : 4192
969  * Primal Bound : +1.80000000000000e+01 (283 solutions)
970  * Dual Bound : +1.80000000000000e+01
971  * Gap : 0.00 %
972  *
973  * SCIP> display solution
974  *
975  * objective value: 18
976  * x0001 1 (obj:1)
977  * x0003 1 (obj:1)
978  * ...
979  * x0027 1 (obj:1)
980  *
981  * SCIP>
982  * \endcode
983  *
984  * What do we see here? After "optimize", SCIP first goes into presolving. Not much is happening for this instance, just
985  * the linear constraints get upgraded to more specific types. Each round of presolving will be displayed in a single
986  * line, with a short summary at the end. Here, there has only been one round with actual changes, the second round did
987  * not bring any further reductions. Thus, it is not displayed and presolving is stopped. Then, we see the actual
988  * solving process. The first three output lines indicate that new incumbent solutions were found by the primal
989  * heuristics with display characters "t", "R", and "s"; see, how the "primalbound" column goes down from 27 to 25. In
990  * the fourth line, two "cuts" are added. Up to here, we needed 44 "LP iter"ations (34 for the first LP and 10 more to
991  * resolve after adding cuts). Little later, the root node processing is finished. We see that there are now two open
992  * nodes in the "left" column. From now on, we will see an output line every hundredth node or whenever a new incumbent
993  * is found (e.g. at node 14 in the above output). After some more nodes, the "dualbound" starts moving, too. At one
994  * point, both will be the same, and the solving process terminates, showing us some wrap-up information.
995  *
996  * The exact performance varies amongst different architectures, operating systems, and so on. Do not be worried if
997  * your installation needs more or less time or nodes to solve. Also, this instance has more than 2000 different optimal
998  * solutions. The optimal objective value always has to be 18, but the solution vector may differ. If you are interested
999  * in this behavior, which is called "performance variability", you may have a look at the MIPLIB2010 paper.
1000  *
1001  * We might want to have some more information now. Which were the heuristics that found the solutions? What plugins
1002  * were called during the solutions process and how much time did they spend? How did the instance that we were solving
1003  * look? Information on certain plugin types (e.g., heuristics, branching rules, separators) we get by
1004  * "display <plugin-type>", information on the solution process, we get by "display statistics", and "display problem"
1005  * shows us the current instance.
1006  *
1007  \code
1008  * SCIP> display heuristics
1009  * primal heuristic c priority freq ofs description
1010  * ---------------- - -------- ---- --- -----------
1011  * trivial t 10000 0 0 start heuristic which tries some trivial solutions
1012  * ...
1013  * rounding R -1000 1 0 LP rounding heuristic with infeasibility recovering
1014  * shifting s -5000 10 0 LP rounding heuristic with infeasibility recovering also using continuous variables
1015  * ...
1016  * SCIP> display statistics
1017  * ...
1018  * gomory : 0.02 6 0 0 461 0
1019  * cgmip : 0.00 0 0 0 0 0
1020  * strongcg : 0.01 6 0 0 598 0
1021  * ...
1022  * oneopt : 0.01 4 1
1023  * coefdiving : 0.02 57 0
1024  * ...
1025  * primal LP : 0.00 0 0 0.00 -
1026  * dual LP : 0.20 4187 14351 3.43 71755.00
1027  * ...
1028  * \endcode
1029  *
1030  * We see that rounding and shifting were the heuristics producing the solutions in the beginning. Rounding is called at
1031  * every node, shifting only at every tenth level of the tree. The statistics are quite comprehensive, thus, we just
1032  * explain a few lines here. We get information for all types of plugins and for the overall solving process. Besides
1033  * others, we see that in six calls, the gomory cut separator and the strong Chv&aacute;tal-Gomory separator each produced
1034  * several hundred cuts (of which only a few entered the LP). The oneopt heuristic found one solution in 4 calls,
1035  * whereas coefdiving failed all 57 times it was called. All the LPs have been solved with the dual simplex algorithm, which
1036  * took about 0.2 seconds of the 0.7 seconds overall solving time.
1037  *
1038  * Now, we can start playing around with parameters. Rounding and shifting seem to be quite successful on this instance,
1039  * wondering what happens if we disable them? Or what happens, if we are even more rigorous and disable all heuristics?
1040  * Or if we do the opposite and use aggressive heuristics?
1041  *
1042  * \code
1043  * SCIP> set
1044  *
1045  * <branching> change parameters for branching rules
1046  * ...
1047  * <heuristics> change parameters for primal heuristics
1048  *
1049  * SCIP/set> heuristics
1050  *
1051  * <actconsdiving> LP diving heuristic that chooses fixings w.r.t. the active constraints
1052  * ...
1053  * <shifting> LP rounding heuristic with infeasibility recovering also using continuous variables
1054  * ...
1055  *
1056  * SCIP/set/heuristics> shifting
1057  *
1058  * <advanced> advanced parameters
1059  * freq frequency for calling primal heuristic <shifting> (-1: never, 0: only at depth freqofs) [10]
1060  * freqofs frequency offset for calling primal heuristic <shifting> [0]
1061  *
1062  * SCIP/set/heuristics/shifting> freq
1063  * current value: 10, new value [-1,2147483647]: -1
1064  * heuristics/shifting/freq = -1
1065  *
1066  * SCIP> se he rou freq -1
1067  * heuristics/rounding/freq = -1
1068  *
1069  * SCIP> re check/instances/MIP/stein27.mps
1070  * original problem has 27 variables (27 bin, 0 int, 0 impl, 0 cont) and 118 constraints
1071  * SCIP> o
1072  *
1073  * feasible solution found by trivial heuristic, objective value 2.700000e+01
1074  * ...
1075  * z 0.1s| 3 | 4 | 140 | 10.5 |1060k| 2 | 22 | 27 | 118 | 27 | 123 | 14 | 0 | 66 | 1.300000e+01 | 1.900000e+01 | 46.15%
1076  * z 0.1s| 6 | 7 | 176 | 11.4 |1063k| 5 | 18 | 27 | 118 | 27 | 123 | 14 | 0 | 118 | 1.300000e+01 | 1.900000e+01 | 46.15%
1077  * * 0.1s| 39 | 28 | 386 | 7.0 |1092k| 14 | - | 27 | 118 | 27 | 123 | 14 | 0 | 199 | 1.300000e+01 | 1.800000e+01 | 38.46%
1078  * ...
1079  * SCIP Status : problem is solved [optimal solution found]
1080  * Solving Time (sec) : 0.75
1081  * Solving Nodes : 4253
1082  * Primal Bound : +1.80000000000000e+01 (287 solutions)
1083  * Dual Bound : +1.80000000000000e+01
1084  * Gap : 0.00 %
1085  *
1086  * SCIP>
1087  * \endcode
1088  *
1089  * We can navigate through the menus step-by-step and get a list of available options and submenus. Thus, we select
1090  * "set" to change settings, "heuristics" to change settings of primal heuristics, "shifting" for that particular
1091  * heuristic. Then we see a list of parameters (and yet another submenu for advanced parameters), and disable this
1092  * heuristic by setting its calling frequency to -1. If we already know the path to a certain setting, we can directly
1093  * type it (as for the rounding heuristic in the above example). Note that we do not have to use the full names, but we
1094  * may use short versions, as long as they are unique.
1095  *
1096  * To solve a problem a second time, we have to read it and start the optimization process again.
1097  *
1098  * \code
1099  * SCIP> set default
1100  * reset parameters to their default values
1101  * SCIP> set heuristics emphasis
1102  *
1103  * aggressive sets heuristics <aggressive>
1104  * fast sets heuristics <fast>
1105  * off turns <off> all heuristics
1106  *
1107  * SCIP/set/heuristics/emphasis> aggr
1108  * heuristics/veclendiving/freq = 5
1109  * ...
1110  * heuristics/crossover/minfixingrate = 0.5
1111  * SCIP> read check/instances/MIP/stein27.mps
1112  * original problem has 27 variables (27 bin, 0 int, 0 impl, 0 cont) and 118 constraints
1113 
1114  * SCIP> opt
1115  * ...
1116  * D 0.1s| 1 | 0 | 107 | - | 971k| 0 | 24 | 27 | 122 | 27 | 131 | 13 | 4 | 0 | 1.300000e+01 | 1.800000e+01 | 38.46%
1117  * 0.1s| 1 | 0 | 107 | - | 971k| 0 | 24 | 27 | 122 | 27 | 131 | 13 | 4 | 0 | 1.300000e+01 | 1.800000e+01 | 38.46%
1118  * 0.1s| 1 | 0 | 119 | - |1111k| 0 | 24 | 27 | 122 | 27 | 132 | 14 | 4 | 0 | 1.300000e+01 | 1.800000e+01 | 38.46%
1119  * 0.1s| 1 | 2 | 119 | - |1112k| 0 | 24 | 27 | 122 | 27 | 132 | 14 | 4 | 24 | 1.300000e+01 | 1.800000e+01 | 38.46%
1120  * time | node | left |LP iter|LP it/n| mem |mdpt |frac |vars |cons |cols |rows |cuts |confs|strbr| dualbound | primalbound | gap
1121  * 0.2s| 100 | 59 | 698 | 5.8 |1138k| 14 | 11 | 27 | 122 | 27 | 123 | 14 | 4 | 204 | 1.300000e+01 | 1.800000e+01 | 38.46%
1122  * 0.2s| 200 | 91 | 1226 | 5.6 |1155k| 14 | - | 27 | 122 | 27 | 123 | 14 | 4 | 207 | 1.300000e+01 | 1.800000e+01 | 38.46%
1123  * ^Cpressed CTRL-C 1 times (5 times for forcing termination)
1124  *
1125  * SCIP Status : solving was interrupted [user interrupt]
1126  * Solving Time (sec) : 0.32
1127  * Solving Nodes : 216
1128  * Primal Bound : +1.80000000000000e+01 (283 solutions)
1129  * Dual Bound : +1.30000000000000e+01
1130  * Gap : 38.46 %
1131  *
1132  * SCIP>
1133  * \endcode
1134  *
1135  * Okay, what happened here? First, we reset all parameters to their default values, using "set default". Next, we
1136  * loaded some meta-parameter settings (also see <a href="http://scip.zib.de/#faq">the FAQ</a>), to apply primal heuristics
1137  * more aggressively. SCIP shows us, which single parameters it changed therefor. Now, the optimal solution is already
1138  * found at the root node, by a heuristic which is deactivated by default. Then, after node 200, the user pressed
1139  * CTRL-C which interrupts the solving process, We see that now in the short status report, primal and dual bound are
1140  * different, thus, the problem is not solved yet. Nevertheless, we could access statistics, see the current incumbent
1141  * solution, change parameters and so on. Entering "optimize" we continue the solving process from the point on at which
1142  * it has been interrupted.
1143  *
1144  * SCIP can also write information to files. E.g., we could store the incumbent solution to a file, or output the
1145  * problem instance in another file format (the LP format is much more human readable than the MPS format, for example).
1146  *
1147  * \code
1148  * SCIP> write solution stein27.sol
1149  *
1150  * written solution information to file <stein27.sol>
1151  *
1152  * SCIP> write problem stein27.lp
1153  * written original problem to file <stein27.lp>
1154  *
1155  * SCIP> q
1156  * ...
1157  * \endcode
1158  *
1159  * We hope this tutorial gave you an overview of what is possible using the SCIP interactive shell. Please also read our
1160  * \ref FAQ, in particular the section <a href="http://scip.zib.de/#faq">Using SCIP as a standalone MIP/MINLP-Solver</a>.
1161  */
1162 
1163 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
1164 /**@page DOC How to search the documentation for interface methods
1165  *
1166  * If you are looking for a method in order to perform a specific task, there are usually two places to look at:
1167  * - The file "scip.h" in the file list.
1168  * In this main header file, you find all methods that perform "complex" operations that affect or need data from
1169  * different components of SCIP.
1170  * For these methods, you always have to provide the SCIP pointer that is created by SCIPcreate().
1171  * The documentation of "scip.h" is grouped into several blocks, each dealing with methods for a specific kind of
1172  * object.
1173  * For example, all methods operating on variables are grouped together.
1174 
1175  * - The files \ref PUBLICMETHODS "pub_<...>.h" contain methods that perform "easy" operations that only
1176  * affect the corresponding objects.
1177  * Usually, with these methods you can access the data of the object.
1178  * For example, in "pub_var.h" you find methods to get information about a variable.
1179  *
1180  * The file "pub_misc.h" contains methods for data structures like priority queues, hash tables, and hash maps,
1181  * as well as methods for sorting, numerics, random numbers, string operations, and file operations.
1182  *
1183  * If you are looking for a description of a callback method of a plugin that you want to implement, you have to
1184  * look at the corresponding \ref TYPEDEFINITIONS "type_<...>.h".
1185  */
1186 
1187 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
1188 /**@page CONS How to add constraint handlers
1189  *
1190  * A constraint handler defines the semantics and the algorithms to process constraints of a certain class. A single
1191  * constraint handler is responsible for all constraints belonging to its constraint class. For example, there is
1192  * one \ref cons_knapsack.h "knapsack constraint handler" that ensures solutions are only accepted if they satisfy all
1193  * knapsack constraints in the model. \n A complete list of all constraint handlers contained in this release can be
1194  * found \ref CONSHDLRS "here".
1195  *
1196  * We now explain how users can add their own constraint handlers.
1197  * For an example, look into the subtour constraint handler (examples/TSP/src/ConshdlrSubtour.cpp) of the
1198  * <a href="http://scip.zib.de/doc/examples/TSP">TSP </a> example project.
1199  * The example is written in C++ and uses the C++ wrapper classes.
1200  * However, we will explain the implementation of a constraint handler using the C interface.
1201  * It is very easy to transfer the C explanation to C++; whenever a method should be implemented using the
1202  * SCIP_DECL_CONS... notion, reimplement the corresponding virtual member function of the abstract scip::ObjConshdlr
1203  * base class.
1204  *
1205  * Additional documentation for the callback methods of a constraint handler can be found in the file
1206  * type_cons.h.
1207  *
1208  * Here is what you have to do (assuming your constraint handler should be named "subtour"):
1209  * -# Copy the template files src/scip/cons_xyz.c and src/scip/cons_xyz.h into files "cons_subtour.c"
1210  * and "cons_subtour.h".
1211  * \n
1212  * Make sure to <b>adjust your Makefile</b> such that these files are compiled and linked to your project.
1213  * -# Use SCIPincludeConsSubtour() in order to include the constraint handler into your SCIP instance,
1214  * e.g., in the main file of your project (see, e.g., src/cppmain.cpp in the TSP example).
1215  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "subtour".
1216  * -# Adjust the \ref CONS_PROPERTIES "properties of the constraint handler".
1217  * -# Define the \ref CONS_DATA "constraint data and the constraint handler data". This is optional.
1218  * -# Implement the \ref CONS_INTERFACE "interface methods".
1219  * -# Implement the \ref CONS_FUNDAMENTALCALLBACKS "fundamental callback methods".
1220  * -# Implement the \ref CONS_ADDITIONALCALLBACKS "additional callback methods". This is optional.
1221  *
1222  *
1223  * @section CONS_PROPERTIES Properties of a Constraint Handler
1224  *
1225  * At the top of the new file "cons_subtour.c" you can find the constraint handler properties.
1226  * These are given as compiler defines. Some of them are optional, as, e.g., separation-related properties,
1227  * which only have to be defined if the constraint handler supports the related callbacks.
1228  * In the C++ wrapper class, you have to provide the constraint handler properties by calling the constructor
1229  * of the abstract base class scip::ObjConshdlr from within your constructor (see the TSP example).
1230  * The properties you have to set have the following meaning:
1231  *
1232  * @subsection CONS_FUNDAMENTALPROPERTIES Fundamental Constraint Handler properties
1233  *
1234  * \par CONSHDLR_NAME: the name of the constraint handler.
1235  * This name is used in the interactive shell to address the constraint handler.
1236  * Additionally, if you are searching for a constraint handler with SCIPfindConshdlr(), this name is looked up.
1237  * Names have to be unique: no two constraint handlers may have the same name.
1238  *
1239  * \par CONSHDLR_DESC: the description of the constraint handler.
1240  * This string is printed as a description of the constraint handler in the interactive shell of SCIP.
1241  *
1242  * \par CONSHDLR_ENFOPRIORITY: the priority of the constraint handler for constraint enforcing.
1243  * Like the separation priority, the enforcement priorities define the order in which the different constraint handlers
1244  * are called in the constraint enforcement step of the subproblem processing.
1245  * The constraint enforcement is called after the price-and-cut loop is executed (in the case that the LP is solved
1246  * at the current subproblem).
1247  * \n
1248  * The integrality constraint handler has an enforcement priority of 0.
1249  * That means, if a constraint handler has negative enforcement priority, it only has to deal with integral solutions
1250  * in its enforcement methods, because for fractional solutions, the integrality constraint handler would have
1251  * created a branching, thereby aborting the enforcement step.
1252  * If you want to implement a constraint-depending branching rule (for example, SOS branching on special ordered
1253  * set constraints), you have to assign a positive enforcement priority to your constraint handler.
1254  * In this case, you have to be able to deal with fractional solutions.
1255  * \n
1256  * See \ref CONSENFOLP and \ref CONSENFOPS for further details of the separation callback.
1257  *
1258  * \par CONSHDLR_CHECKPRIORITY: the priority of the constraint handler for checking feasibility.
1259  * Like the separation priority, the checking priorities define the order in which the different constraint handlers
1260  * are called to check the feasibility of a given primal solution candidate.
1261  * The integrality constraint handler has a checking priority of 0.
1262  * That means, constraint handlers with negative checking priorities only have to deal with integral solutions.
1263  *
1264  * \par CONSHDLR_EAGERFREQ: the default frequency for using all instead of only the useful constraints in separation, propagation and enforcement.
1265  * If \em constraint \em aging is activated, some constraints that were not useful in the past for propagation or
1266  * separation are marked to be \em obsolete.
1267  * Usually, the obsolete constraints are not presented to the separation and propagation methods of the constraint
1268  * handlers, such that the constraint handlers only process the non-obsolete constraints.
1269  * However, every n'th call, with n being the EAGERFREQ of the constraint handler, all constraints are presented to the
1270  * separation and propagation methods of the constraint handler.
1271  * This gives obsolete constraints the chance of becoming non-obsolete again.
1272  * \n
1273  * If the eager evaluation frequency is set to -1, obsolete constraints are never presented to the separation and
1274  * propagation methods.
1275  * A frequency of 0 means, that obsolete constraints are only used in the first call of each method.
1276  *
1277  * \par CONSHDLR_NEEDSCONS: indicates whether the constraint handler should be skipped, if no constraints are available.
1278  * Usually, a constraint handler is only executed if there are constraints of its corresponding class in the model.
1279  * For those constraint handlers, the NEEDSCONS flag should be set to TRUE.
1280  * However, some constraint handlers must be called without having a constraint of the class in the model, because
1281  * the constraint is only implicitly available.
1282  * For example, the integrality constraint handler has the NEEDSCONS flag set to FALSE, because there is no explicit
1283  * integrality constraint in the model.
1284  * The integrality conditions are attached to the variables, and the integrality constraint handler has to check
1285  * all variables that are marked to be integer for integral values.
1286  *
1287  * @subsection CONS_ADDITIONALPROPERTIES Optional Constraint Handler properties
1288  *
1289  * The following properties are optional and only need to be defined if the constraint handlers support
1290  * separation, presolving, propagation, and/or upgrade functionality.
1291  *
1292  * \par LINCONSUPGD_PRIORITY: priority of the constraint handler for upgrading of linear constraints
1293  * This property is only needed if a certain linear constraint can be upgraded to a more specific one. In one of
1294  * the first presolving rounds SCIP tries to upgrade linear constraints to more specialized constraints, such as
1295  * knapsack constraints. The upgrading calls are processed in the order of decreasing priority.
1296  *
1297  * \par NONLINCONSUPGD_PRIORITY: priority of the constraint handler for upgrading of nonlinear constraints
1298  * This property has the same effect as the LINCONSUPGD_PRIORITY parameter, see above, and should be set whenever
1299  * an upgrade functionality from a general nonlinear constraint to the more specific one is defined.
1300  *
1301  * \par CONSHDLR_SEPAFREQ: the default frequency for separating cuts.
1302  * The separation frequency defines the depth levels at which the constraint handler's separation methods \ref CONSSEPALP
1303  * and \ref CONSSEPASOL are called.
1304  * For example, a separation frequency of 7 means, that the separation callback is executed for subproblems that are
1305  * in depth 0, 7, 14, ... of the branching tree.
1306  * A separation frequency of 0 means, that the separation method is only called at the root node.
1307  * A separation frequency of -1 disables the separation method of the constraint handler.
1308  * \n
1309  * The separation frequency can be adjusted by the user.
1310  * This property of the constraint handler only defines the default value of the frequency.
1311  * If you want to have a more flexible control of when to execute the separation algorithm, you have to assign
1312  * a separation frequency of 1 and implement a check at the beginning of your separation algorithm whether you really
1313  * want to execute the separator or not.
1314  * If you do not want to execute the method, set the result code to SCIP_DIDNOTRUN.
1315  *
1316  * \par CONSHDLR_SEPAPRIORITY: the priority of the constraint handler for separation. (optional: to be set only if the constraint handler supports separation)
1317  * In each separation round during the price-and-cut loop of the subproblem processing or during the separation loop
1318  * of the primal solution separation, the separators and separation methods of the constraint handlers are called in
1319  * a predefined order, which is given by the priorities of the separators and the separation priorities of the
1320  * constraint handlers.
1321  * First, the separators with non-negative priority are called in the order of decreasing priority.
1322  * Next, the separation methods of the different constraint handlers are called in the order of decreasing separation
1323  * priority.
1324  * Finally, the separators with negative priority are called in the order of decreasing priority.
1325  * \n
1326  * The separation priority of the constraint handler should be set according to the complexity of the cut separation
1327  * algorithm and the impact of the resulting cuts:
1328  * Constraint handlers that provide fast algorithms that usually have a high impact (i.e., cut off a large portion of
1329  * the LP relaxation) should have a high priority.
1330  * See \ref CONSSEPALP and \ref CONSSEPASOL for further details of the separation callbacks.
1331  *
1332  * \par CONSHDLR_DELAYSEPA: the default for whether the separation method should be delayed, if other separators found cuts.
1333  * If the constraint handler's separation method is marked to be delayed, it is only executed after no other separator
1334  * or constraint handler found a cut during the price-and-cut loop.
1335  * If the separation method of the constraint handler is very expensive, you may want to mark it to be delayed until all
1336  * cheap separation methods have been executed.
1337  *
1338  * \par CONSHDLR_PROPFREQ: the default frequency for propagating domains.
1339  * This default frequency has the same meaning as the CONSHDLR_SEPAFREQ with respect to the domain propagation
1340  * callback of the constraint handler.
1341  * A propagation frequency of 0 means that propagation is only applied in preprocessing and at the root node.
1342  * A propagation frequency of -1 disables the propagation method of the constraint handler.
1343  *
1344  * \par CONSHDLR_DELAYPROP: the default for whether the propagation method should be delayed, if other propagators found reductions.
1345  * This property is analogous to the DELAYSEPA flag, but deals with the propagation method of the constraint handler.
1346  *
1347  * \par CONSHDLR_PROP_TIMING: the propagation timing mask of the constraint handler.
1348  * SCIP calls the domain propagation routines at different places in the node processing loop.
1349  * This property indicates at which places the propagation routine of the constraint handler is called.
1350  * Possible values are defined in type_timing.h and can be concatenated, e.g., as in SCIP_PROPTIMING_ALWAYS.
1351  *
1352  * \par CONSHDLR_MAXPREROUNDS: the default maximal number of presolving rounds the constraint handler participates in.
1353  * The preprocessing is executed in rounds.
1354  * If enough changes have been applied to the model, an additional preprocessing round is performed.
1355  * The MAXPREROUNDS parameter of a constraint handler denotes the maximal number of preprocessing rounds the constraint
1356  * handler participates in.
1357  * A value of -1 means that there is no limit on the number of rounds.
1358  * A value of 0 means the preprocessing callback of the constraint handler is disabled.
1359  *
1360  * \par CONSHDLR_DELAYPRESOL: the default for whether the presolving method should be delayed, if other presolvers found reductions.
1361  * This property is analogous to the DELAYSEPA flag, but deals with the preprocessing method of the constraint handler.
1362  *
1363  *
1364  *
1365  * @section CONS_DATA Constraint Data and Constraint Handler Data
1366  *
1367  * Below the header "Data structures" you can find two structs called "struct SCIP_ConsData" and
1368  * "struct SCIP_ConshdlrData".
1369  * If you are using C++, you only need to define the "struct SCIP_ConsData".
1370  * The constraint handler data must be implemented as member variables of your constraint handler class.
1371  * \n
1372  * The constraint data are the information that is needed to define a single constraint of the constraint handler's
1373  * constraint class.
1374  * For example, the data of a knapsack constraint would consist of a list of variables, a list of weights, and
1375  * the capacity of the knapsack.
1376  * The data of a subtour constraint consists of the graph on which the problem is defined.
1377  * In the graph, each edge should be linked to the corresponding binary problem variable.
1378  * \n
1379  * The constraint handler data are additional variables, that belong to the constraint handler itself and which are
1380  * not specific to a single constraint.
1381  * For example, you can use these data to store parameters of the constraint handler or statistical information.
1382  * The constraint handler data are optional.
1383  * You can leave the struct empty.
1384  *
1385  *
1386  * @section CONS_INTERFACE Interface Methods
1387  *
1388  * At the bottom of "cons_subtour.c" you can find three interface methods, that also appear in "cons_subtour.h".
1389  * These are SCIPincludeConshdlrSubtour(), SCIPcreateConsSubtour(), and SCIPcreateConsSubtourBasic().
1390  * \n
1391  * The method SCIPincludeConshdlrSubtour() only has to be adjusted slightly.
1392  * It is responsible for notifying SCIP of the presence of the constraint handler by calling the method
1393  * SCIPincludeConshdlr().
1394  * It is called by the user, if (s)he wants to include the constraint handler, i.e., if (s)he wants to make
1395  * the constraint handler available to the model, and looks like this:
1396  * -# If you are using constraint handler data, you have to <b>allocate the memory for the data</b> at this point.
1397  * You also have to initialize the fields in struct SCIP_ConshdlrData afterwards.
1398  * \code
1399  * SCIP_RETCODE SCIPincludeConshdlrKnapsack(
1400  * ...
1401  * )
1402  * {
1403  * SCIP_EVENTHDLRDATA* eventhdlrdata;
1404  * SCIP_CONSHDLRDATA* conshdlrdata;
1405  * SCIP_CONSHDLR* conshdlr;
1406  *
1407  * SCIP_CALL( SCIPallocMemory(scip, &conshdlrdata) );
1408  * ...
1409  * \endcode
1410  * -# Now, <b>SCIP gets notified</b> of the presence of the constraint handler together with its \ref CONS_FUNDAMENTALCALLBACKS "basic callbacks".
1411  * \code
1412  * SCIP_CALL( SCIPincludeConshdlrBasic(scip, &conshdlr, CONSHDLR_NAME, CONSHDLR_DESC,
1413  * CONSHDLR_ENFOPRIORITY, CONSHDLR_CHECKPRIORITY, CONSHDLR_EAGERFREQ, CONSHDLR_NEEDSCONS,
1414  * consEnfolpKnapsack, consEnfopsKnapsack, consCheckKnapsack, consLockKnapsack,
1415  * conshdlrdata) );
1416  * assert(conshdlr != NULL);
1417  * \endcode
1418  * -# All \ref CONS_ADDITIONALCALLBACKS "additional callbacks" are added via their setter functions.
1419  * \code
1420  * SCIP_CALL( SCIPsetConshdlrCopy(scip, conshdlr, conshdlrCopyKnapsack, consCopyKnapsack) );
1421  * SCIP_CALL( SCIPsetConshdlrTrans(scip, conshdlr, consTransKnapsack) );
1422  * \endcode
1423  * -# If the constraint handler is a specialization of a general linear or nonlinear constraint, we want to include an <b>automatic
1424  * upgrading mechanism</b> by calling the interface method
1425  * \code
1426  * if( SCIPfindConshdlr(scip,"linear") != NULL )
1427  * {
1428  * SCIP_CALL( SCIPincludeLinconsUpgrade(scip, linconsUpgdKnapsack, LINCONSUPGD_PRIORITY, CONSHDLR_NAME) );
1429  * }
1430  * \endcode
1431  * or
1432  * \code
1433  * SCIP_CALL( SCIPincludeNonlinconsUpgrade(scip, nonlinconsUpgdSubtour, NULL, NONLINCONSUPGD_PRIORITY, TRUE, CONSHDLR_NAME) );
1434  * \endcode
1435  * in the nonlinear case.
1436  * See also cons_nonlinear.h for further information about the general upgrade procedure in the nonlinear case.
1437  * -# You may also add <b>user parameters</b> for your constraint handler.
1438  * Some parameters which are important to play with are added to every constraint automatically, as, e.g.,
1439  * propagation or separation frequency.
1440  * \code
1441  * SCIP_CALL( SCIPaddIntParam(scip,
1442  * "constraints/knapsack/sepacardfreq",
1443  * "multiplier on separation frequency, how often knapsack cuts are separated (-1: never, 0: only at root)",
1444  * &conshdlrdata->sepacardfreq, TRUE, DEFAULT_SEPACARDFREQ, -1, INT_MAX, NULL, NULL) );
1445  * ...
1446  * return SCIP_OKAY;
1447  * }
1448  * \endcode
1449  *
1450  *
1451  *
1452  *
1453  * The methods SCIPcreateConsSubtour() and SCIPcreateConsSubtourBasic() are called to create a single constraint of the constraint
1454  * handler's constraint class.
1455  * It should allocate and fill the constraint data, and call SCIPcreateCons().
1456  * Take a look at the following example from the \ref cons_knapsack.h "knapsack constraint handler":
1457  *
1458  * \code
1459  * SCIP_RETCODE SCIPcreateConsKnapsack(
1460  * SCIP* scip,
1461  * SCIP_CONS** cons,
1462  * const char* name,
1463  * int nvars,
1464  * SCIP_VAR** vars,
1465  * SCIP_Longint* weights,
1466  * SCIP_Longint capacity,
1467  * SCIP_Bool initial,
1468  * SCIP_Bool separate,
1469  * SCIP_Bool enforce,
1470  * SCIP_Bool check,
1471  * SCIP_Bool propagate,
1472  * SCIP_Bool local,
1473  * SCIP_Bool modifiable,
1474  * SCIP_Bool dynamic,
1475  * SCIP_Bool removable,
1476  * SCIP_Bool stickingatnode
1477  * )
1478  * {
1479  * SCIP_CONSHDLRDATA* conshdlrdata;
1480  * SCIP_CONSHDLR* conshdlr;
1481  * SCIP_CONSDATA* consdata;
1482  *
1483  * conshdlr = SCIPfindConshdlr(scip, CONSHDLR_NAME);
1484  * if( conshdlr == NULL )
1485  * {
1486  * SCIPerrorMessage("knapsack constraint handler not found\n");
1487  * return SCIP_PLUGINNOTFOUND;
1488  * }
1489  *
1490  * conshdlrdata = SCIPconshdlrGetData(conshdlr);
1491  * assert(conshdlrdata != NULL);
1492  * assert(conshdlrdata->eventhdlr != NULL);
1493  *
1494  * SCIP_CALL( consdataCreate(scip, &consdata, conshdlrdata->eventhdlr, nvars, vars, weights, capacity) );
1495  *
1496  * SCIP_CALL( SCIPcreateCons(scip, cons, name, conshdlr, consdata, initial, separate, enforce, check, propagate,
1497  * local, modifiable, dynamic, removable, stickingatnode) );
1498  *
1499  * return SCIP_OKAY;
1500  * }
1501  * \endcode
1502  *
1503  * In this example, consdataCreate() is a local method that allocates memory for the given consdata
1504  * and fills the data with the given <code>vars</code> array. For allocating memory for the constraint data, you
1505  * can use SCIP memory allocation:
1506  * \code
1507  * SCIP_CALL( SCIPallocBlockMemory(scip, consdata) );
1508  * \endcode
1509  *
1510  *
1511  * @section CONS_CALLBACKS Callback methods of Constraint handlers
1512  *
1513  * Besides the various functions which you will implement inside your constraint handler there exists a number
1514  * of <b> callback methods </b> associated with your constraint handler. Callback methods can be regarded as
1515  * tasks which your constraint handler is able to provide to the solver. They are grouped into two
1516  * categories:
1517  *
1518  * \ref CONS_FUNDAMENTALCALLBACKS "Fundamental Callback methods" are mandatory to implement
1519  * such that your code will work. For example, every constraint handler has to provide the
1520  * functionality to state whether all of its constraints are
1521  * fulfilled by a given variable assignment. Hence, the \ref CONSCHECK "CONSCHECK" callback is
1522  * one of the fundamental (or \a basic) callbacks of a constraint handler.
1523  *
1524  * Callbacks which are not necessarily implemented are grouped together as
1525  * \ref CONS_ADDITIONALCALLBACKS "additional callbacks". Such callbacks can be used to allocate and free memory
1526  * at different stages of the solving process. Although not mandatory, it might be useful to implement
1527  * some of these callbacks, e.g., to extend your constraint handler by a
1528  * \ref CONSSEPALP "separation" or \ref CONSPRESOL "presolving" functionality.
1529  *
1530  * All callbacks should be passed to SCIP during the SCIPinclude<PLUGINTYPE><PLUGINNAME> method
1531  * (e.g., SCIPincludeConshdlrKnapsack() for the \ref cons_knapsack.h "knapsack constraint handler").
1532  * Since SCIP version 3.0, two ways of setting callbacks can be used, either via SCIPincludeConshdlr()
1533  * (all at once, as it always was), or via SCIPincludeConshdlrBasic() and setter functions for additional callbacks.
1534  * Since the basic inclusion methods are very unlikely to change and will thus
1535  * make your code more stable towards future versions of SCIP with more callbacks,
1536  * we recommend the latter choice, as explained in the \ref CONS_INTERFACE "interface" section.
1537  *
1538  * @section CONS_FUNDAMENTALCALLBACKS Fundamental Callback Methods
1539  *
1540  * By implementing the fundamental callbacks, you define the semantics of the constraint class the constraint handler
1541  * deals with.
1542  * If these methods are implemented, the resulting code is already correct and finds the optimal solution to the
1543  * given problem instance.
1544  * However, it might be very slow because the additional features, like cut separation and domain propagation, are
1545  * missing.
1546  * In the C++ wrapper class scip::ObjConshdlr, the fundamental callback methods are virtual abstract member functions.
1547  * You have to implement them in order to be able to construct an object of your constraint handler class.
1548  *
1549  * There are three fundamental callback methods that are all dealing with the feasibility of a given solution.
1550  * They are called at different places in the algorithm and have slightly different meaning.
1551  * However, it is usually reasonable to implement a single local method that is called by all of the three callback
1552  * methods with slightly modified parameters.
1553  * The fourth method provides dual information that is used for example in preprocessing.
1554  *
1555  * Additional documentation for the callback methods can be found in type_cons.h.
1556  *
1557  * @subsection CONSCHECK
1558  *
1559  * The CONSCHECK callback gets a primal solution candidate in a SCIP_SOL* data structure
1560  * and has to check this solution for global feasibility.
1561  * It has to return a result SCIP_FEASIBLE, if the solution satisfies all the constraints of the constraint handler,
1562  * and a result SCIP_INFEASIBLE if there is at least one constraint that is violated.
1563  * The callback is used by primal heuristics to check a constructed solution for feasibility.
1564  * That means, the constraint handler has to deal with arbitrary solutions that do not necessarily satisfy the bounds
1565  * and constraints of the local subproblem.
1566  *
1567  * The value of a variable \em var in the given solution \em sol can be accessed by calling
1568  * \code
1569  * SCIPgetSolVal(scip, sol, var)
1570  * \endcode
1571  *
1572  * For example, the \ref cons_knapsack.h "knapsack constraint handler" loops over its constraints and
1573  * calculates the scalar product \f$w^T x\f$ of weights \f$w\f$ with the solution vector \f$x\f$.
1574  * This scalar product is compared with the capacity of the knapsack constraint.
1575  * If it exceeds the capacity, the CONSCHECK method is immediately aborted with the result SCIP_INFEASIBLE.
1576  * If all knapsack constraints are satisfied, a result SCIP_FEASIBLE is returned.
1577  *
1578  * @subsection CONSENFOLP
1579  *
1580  * The CONSENFOLP method is called after the price-and-cut loop was finished and an LP solution is available.
1581  * Like the CHECK call, the ENFOLP method should return a result SCIP_FEASIBLE, if the solution satisfies all the
1582  * constraints.
1583  * However, the behavior should be different, if the solution violates some of the associated constraints.
1584  * The constraint handler may return a result SCIP_INFEASIBLE in this situation, but this is not the best what
1585  * one can do.
1586  * The ENFOLP method has the possibility of \em resolving the infeasibility by
1587  * - stating that the current subproblem is infeasible (result SCIP_CUTOFF),
1588  * - adding an additional constraint that resolves the infeasibility (result SCIP_CONSADDED),
1589  * - reducing the domain of a variable (result SCIP_REDUCEDDOM),
1590  * - adding a cutting plane (result SCIP_SEPARATED),
1591  * - performing a branching (result SCIP_BRANCHED).
1592  *
1593  * However, the solution is not given as a SCIP_SOL* data structure.
1594  *
1595  * The value of a variable <code>var</code> in the LP solution can be accessed by calling
1596  * \code
1597  * SCIPgetVarSol(scip, var)
1598  * \endcode
1599  * or by
1600  * \code
1601  * SCIPgetSolVal(scip, NULL, var)
1602  * \endcode
1603  * By using the latter method, you can have a single local method to check a solution for feasibility by passing
1604  * the given <code>sol</code> to the CONSCHECK call and by passing a NULL pointer as <code>sol</code> to
1605  * the CONSENFOLP and CONSENFOPS calls.
1606  *
1607  *
1608  * @subsection CONSENFOPS
1609  *
1610  * The CONSENFOPS callback is similar to the CONSENFOLP callback, but deals with \em pseudo \em solutions instead
1611  * of LP solutions.
1612  *
1613  * If the LP was not solved at the current subproblem (either because the user did not want to solve it, or because
1614  * numerical difficulties in the LP solving process were detected) no LP solution is available.
1615  * In this situation, the pseudo solution is used instead.
1616  * In this solution, the variables are set to the local bound which is best with respect to the objective function.
1617  * You can think of the pseudo solution as solution to the LP relaxation with all constraints except the bounds
1618  * being removed.
1619  *
1620  * Like the ENFOLP callback, the ENFOPS callback has to check whether the pseudo solution satisfies all the constraints
1621  * of the constraint handler.
1622  * The pseudo solution can be accessed by the same methods as the LP solution (SCIP knows, if the LP was solved at the
1623  * current subproblem, and returns either the LP solution or the pseudo solution).
1624  *
1625  * Unlike the ENFOLP callback, the ENFOPS callback must not add cuts and cannot return the result SCIP_SEPARATED.
1626  * It is, however, possible to force the solving of the LP by returning the result SCIP_SOLVELP.
1627  * For example, the infeasibility of a linear constraint that contains continuous variables cannot be resolved,
1628  * if all integer variables in the constraint are already fixed.
1629  * In this case, the LP has to be solved in order to get a solution that satisfies the linear constraint.
1630  *
1631  * @subsection CONSLOCK
1632  *
1633  * The CONSLOCK callback provides dual information for a single constraint.
1634  * It has to tell SCIP, which variables are existing in the given constraint, and in which way modifications of these
1635  * variables may affect the feasibility of the constraint.
1636  *
1637  * For each variable that is affected by the constraint, the callback should call SCIPaddVarLocks():
1638  * - If the constraint may become violated by decreasing the value of a variable, it should call
1639  * SCIPaddVarLocks(scip, var, nlockspos, nlocksneg), saying that rounding down is potentially rendering the
1640  * (positive) constraint infeasible and rounding up is potentially rendering the negation of the constraint
1641  * infeasible.
1642  * - If the constraint may become violated by increasing the value of a variable, it should call
1643  * SCIPaddVarLocks(scip, var, nlocksneg, nlockspos), saying that rounding up is potentially rendering the
1644  * constraint's negation infeasible and rounding down is potentially rendering the constraint itself
1645  * infeasible.
1646  * - If the constraint may become violated by changing the variable in any direction, it should call
1647  * SCIPaddVarLocks(scip, var, nlockspos + nlocksneg, nlockspos + nlocksneg).
1648  *
1649  * <b>Note:</b> You do not have to worry about nlockspos and nlocksneg. These integer values are given as
1650  * parameter of the CONSLOCK callback (see type_cons.h). Just use these variables in the above described
1651  * fashion <b>without</b> adding or subtracting anything to them. In case of the knapsack constraints this
1652  * method looks like this.
1653  *
1654  * \code
1655  * static
1656  * SCIP_DECL_CONSLOCK(consLockKnapsack)
1657  * {
1658  * SCIP_CONSDATA* consdata;
1659  * int i;
1660  *
1661  * consdata = SCIPconsGetData(cons);
1662  * assert(consdata != NULL);
1663  *
1664  * for( i = 0; i < consdata->nvars; i++)
1665  * {
1666  * SCIP_CALL( SCIPaddVarLocks(scip, consdata->vars[i], nlocksneg, nlockspos) );
1667  * }
1668  *
1669  * return SCIP_OKAY;
1670  * }
1671  * \endcode
1672  *
1673  * To give same more intuition, consider the linear constraint \f$3x -5y +2z \leq 7\f$ as an example.
1674  * The CONSLOCK callback method of the linear constraint handler should call
1675  * SCIPaddVarLocks(scip, x, nlocksneg, nlockspos), SCIPaddVarLocks(scip, y, nlockspos, nlocksneg),
1676  * and SCIPaddVarLocks(scip, z, nlocksneg, nlockspos) to tell SCIP, that rounding up of \f$x\f$
1677  * and \f$z\f$ and rounding down of \f$y\f$ can destroy the feasibility of the constraint, while rounding
1678  * down of \f$x\f$ and \f$z\f$ and rounding up of \f$y\f$ can destroy the feasibility of the
1679  * constraint's negation \f$3x -5y +2z > 7\f$.
1680  * \n
1681  * A linear constraint \f$2 \leq 3x -5y +2z \leq 7\f$ should call
1682  * SCIPaddVarLocks(scip, ..., nlockspos + nlocksneg, nlockspos + nlocksneg) on all variables,
1683  * since rounding in both directions of each variable can destroy both the feasibility of the
1684  * constraint and it's negation \f$3x -5y +2z < 2\f$ or \f$3x -5y +2z > 7\f$.
1685  *
1686  *
1687  * @section CONS_ADDITIONALCALLBACKS Additional Callback Methods
1688  *
1689  * The additional callback methods do not need to be implemented in every case, but provide useful functionality
1690  * for many applications. They can be added to your constraint handler via setter functions, see
1691  * \ref CONS_INTERFACE "here".
1692  *
1693  * @subsection CONSFREE
1694  *
1695  * If you are using constraint handler data, you have to implement this method in order to free the
1696  * constraint handler data. This can be done by the following procedure (which is taken from the
1697  * \ref cons_knapsack.h "knapsack constraint handler"):
1698  *
1699  * \code
1700  * static
1701  * SCIP_DECL_CONSFREE(consFreeKnapsack)
1702  * {
1703  * SCIP_CONSHDLRDATA* conshdlrdata;
1704  *
1705  * conshdlrdata = SCIPconshdlrGetData(conshdlr);
1706  * assert(conshdlrdata != NULL);
1707  *
1708  * SCIPfreeMemory(scip, &conshdlrdata);
1709  *
1710  * SCIPconshdlrSetData(conshdlr, NULL);
1711  *
1712  * return SCIP_OKAY;
1713  * }
1714  * \endcode
1715  *
1716  * If you have allocated memory for fields in your constraint handler data, remember to free this memory
1717  * before freeing the constraint handler data itself.
1718  * If you are using the C++ wrapper class, this method is not available.
1719  * Instead, just use the destructor of your class to free the member variables of your class.
1720  *
1721  * @subsection CONSHDLRCOPY
1722  *
1723  * The CONSHDLRCOPY callback is executed when the SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
1724  * callback as <code>NULL</code> the user disables the inclusion of the specified constraint handler into all copied SCIP
1725  * instances. This may deteriorate the performance of primal heuristics solving sub-SCIPs, since these constitute only
1726  * relaxations of the original problem if constraint handlers are missing.
1727  *
1728  * A usual implementation just
1729  * calls the interface method which includes the constraint handler to the model. For example, this callback is
1730  * implemented for the knapsack constraint handler as follows:
1731  *
1732  * \code
1733  * static
1734  * SCIP_DECL_CONSHDLRCOPY(conshdlrCopyKnapsack)
1735  * {
1736  * assert(scip != NULL);
1737  * assert(conshdlr != NULL);
1738  * assert(strcmp(SCIPconshdlrGetName(conshdlr), CONSHDLR_NAME) == 0);
1739  *
1740  * SCIP_CALL( SCIPincludeConshdlrKnapsack(scip) );
1741  *
1742  * *valid = TRUE;
1743  *
1744  * return SCIP_OKAY;
1745  * }
1746  * \endcode
1747  *
1748  * <b>Note:</b> If you implement this callback, take care when setting the valid pointer. The valid pointer should be
1749  * set to TRUE if (and only if!) you can make sure that all necessary data of the constraint handler are copied
1750  * correctly. If the complete problem is validly copied, i.e. if the copy methods of all problem defining plugins
1751  * (constraint handlers and pricers) return <code>*valid = TRUE</code>, then dual reductions found for the copied problem can be
1752  * transferred to the original SCIP instance. Thus, if the valid pointer is wrongly set to TRUE, it might happen that
1753  * optimal solutions are cut off.
1754  *
1755  * <b>Note:</b> If you implement this callback and the constraint handler needs constraints (see CONSHDLR_NEEDSCONS),
1756  * then you also need to implement the callback \ref CONSCOPY.
1757  *
1758  * @subsection CONSINIT
1759  *
1760  * The CONSINIT callback is executed after the problem is transformed.
1761  * The constraint handler may, e.g., use this call to replace the original variables in its constraints by transformed
1762  * variables, or to initialize its statistical constraint handler data.
1763  *
1764  * @subsection CONSEXIT
1765  *
1766  * The CONSEXIT callback is executed before the transformed problem is freed.
1767  * In this method, the constraint handler should free all resources that were allocated for the solving process.
1768  *
1769  * @subsection CONSINITPRE
1770  *
1771  * The CONSINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
1772  * The constraint handler may use this call to initialize its presolving data, or to modify its constraints
1773  * before the presolving process begins.
1774  * Necessary constraint modifications that have to be performed even if presolving is turned off should be done here
1775  * or in the presolving deinitialization call.
1776  *
1777  * @subsection CONSEXITPRE
1778  *
1779  * The CONSEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
1780  * The constraint handler may use this call e.g. to clean up its presolving data, or to finally modify its constraints
1781  * before the branch-and-bound process begins.
1782  * Necessary constraint modifications that have to be performed even if presolving is turned off should be done here
1783  * or in the presolving initialization call.
1784  * Besides necessary modifications and clean up, no time consuming operations should be done.
1785  *
1786  * @subsection CONSINITSOL
1787  *
1788  * The CONSINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
1789  * begin.
1790  * The constraint handler may use this call to initialize its branch-and-bound specific data.
1791  *
1792  * @subsection CONSEXITSOL
1793  *
1794  * The CONSEXITSOL callback is executed before the branch-and-bound process is freed.
1795  * The constraint handler should use this call to clean up its branch-and-bound data, in particular to release
1796  * all LP rows that it has created or captured.
1797  *
1798  * @subsection CONSDELETE
1799  *
1800  * The CONSDELETE callback is executed if a constraint should be freed.
1801  * You can think of it as the destructor of a single constraint.
1802  * In the callback, you have to free the given constraint data.
1803  * The CONSDELETE callback is therefore the counterpart of the SCIPcreateCons...() interface method and the CONSTRANS
1804  * method.
1805  *
1806  * @subsection CONSTRANS
1807  *
1808  * The CONSTRANS method is called for each constraint of the constraint handler, when the user starts the solving
1809  * process.
1810  * It has to copy the original constraint data of the constraint to the memory for the transformed problem.
1811  * You can think of it as a copy constructor for a single constraint.
1812  *
1813  * The original model is copied in order to protect it from transformations that are applied during the solving process,
1814  * in particular during preprocessing.
1815  * Preprocessing and solving always operates on the transformed problem.
1816  * If the solving process data are freed, the original data still exist and the user can, e.g., modify the problem and
1817  * restart the solving process.
1818  *
1819  * If you do not implement the CONSTRANS method, a transformed constraint is created with the same flags and the
1820  * same constraint data pointer.
1821  * That means, the transformed constraint points to the original constraint data.
1822  * This is okay, as long as the constraint data is not changed during the solving process.
1823  * If you want to implement preprocessing methods or other methods that modify the constraint data, you have to
1824  * implement the CONSTRANS method and create a copy of the constraint data.
1825  *
1826  * Here is an example, which is taken from the \ref cons_knapsack.h "knapsack constraint handler":
1827  * \code
1828  * static
1829  * SCIP_DECL_CONSTRANS(consTransKnapsack)
1830  * {
1831  * SCIP_CONSHDLRDATA* conshdlrdata;
1832  * SCIP_CONSDATA* sourcedata;
1833  * SCIP_CONSDATA* targetdata;
1834  *
1835  * assert(conshdlr != NULL);
1836  * assert(strcmp(SCIPconshdlrGetName(conshdlr), CONSHDLR_NAME) == 0);
1837  * assert(SCIPgetStage(scip) == SCIP_STAGE_TRANSFORMING);
1838  * assert(sourcecons != NULL);
1839  * assert(targetcons != NULL);
1840  *
1841  * sourcedata = SCIPconsGetData(sourcecons);
1842  * assert(sourcedata != NULL);
1843  * assert(sourcedata->row == NULL);
1844  *
1845  * conshdlrdata = SCIPconshdlrGetData(conshdlr);
1846  * assert(conshdlrdata != NULL);
1847  * assert(conshdlrdata->eventhdlr != NULL);
1848  *
1849  * SCIP_CALL( consdataCreate(scip, &targetdata, conshdlrdata->eventhdlr,
1850  * sourcedata->nvars, sourcedata->vars, sourcedata->weights, sourcedata->capacity) );
1851  *
1852  * SCIP_CALL( SCIPcreateCons(scip, targetcons, SCIPconsGetName(sourcecons), conshdlr, targetdata,
1853  * SCIPconsIsInitial(sourcecons), SCIPconsIsSeparated(sourcecons), SCIPconsIsEnforced(sourcecons),
1854  * SCIPconsIsChecked(sourcecons), SCIPconsIsPropagated(sourcecons),
1855  * SCIPconsIsLocal(sourcecons), SCIPconsIsModifiable(sourcecons),
1856  * SCIPconsIsDynamic(sourcecons), SCIPconsIsRemovable(sourcecons), SCIPconsIsStickingAtNode(sourcecons)) );
1857  *
1858  * return SCIP_OKAY;
1859  * }
1860  * \endcode
1861  *
1862  * @subsection CONSINITLP
1863  *
1864  * The CONSINITLP callback is executed before the first LP relaxation is solved.
1865  * It should add the LP relaxations of all "initial" constraints to the LP. The method should scan the constraints
1866  * array for constraints that are marked initial via calls to SCIPconsIsInitial() and put the LP relaxation
1867  * of all initial constraints to the LP with calls to SCIPaddCut().
1868  *
1869  * @subsection CONSSEPALP
1870  *
1871  * The CONSSEPALP callback is executed during the price-and-cut loop of the subproblem processing.
1872  * It should try to generate cutting planes for the constraints of the constraint handler in order to separate
1873  * the current LP solution.
1874  * The method is called in the LP solution loop, which means that a valid LP solution exists.
1875  *
1876  * Usually, a separation callback searches and produces cuts, that are added with a call to SCIPaddCut().
1877  * If the cut should be remembered in the global cut pool, it may also call SCIPaddPoolCut().
1878  * However, the callback may also produce domain reductions or add other constraints.
1879  *
1880  * The CONSSEPALP callback has the following options:
1881  * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1882  * - adding an additional constraint (result SCIP_CONSADDED)
1883  * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1884  * - adding a cutting plane to the LP (result SCIP_SEPARATED)
1885  * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
1886  * (result SCIP_DIDNOTFIND)
1887  * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
1888  * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
1889  * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
1890  *
1891  * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1892  * CONSHDLR_SEPAFREQ, CONSHDLR_SEPAPRIORITY, and CONSHDLR_DELAYSEPA, which influence the behaviour of SCIP
1893  * calling CONSSEPALP.
1894  *
1895  * @subsection CONSSEPASOL
1896  *
1897  * The CONSSEPASOL callback is executed during separation loop on arbitrary primal solutions.
1898  * It should try to generate cutting planes for the constraints of the constraint handler in order to separate
1899  * the given primal solution.
1900  * The method is not called in the LP solution loop, which means that there is no valid LP solution.
1901  *
1902  * Usually, a separation callback searches and produces cuts, that are added with a call to SCIPaddCut().
1903  * If the cut should be remembered in the global cut pool, it may also call SCIPaddPoolCut().
1904  * However, the callback may also produce domain reductions or add other constraints.
1905  *
1906  * The CONSSEPASOL callback has the following options:
1907  * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1908  * - adding an additional constraint (result SCIP_CONSADDED)
1909  * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1910  * - adding a cutting plane to the LP (result SCIP_SEPARATED)
1911  * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
1912  * (result SCIP_DIDNOTFIND)
1913  * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
1914  * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
1915  * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
1916  *
1917  * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1918  * CONSHDLR_SEPAFREQ, CONSHDLR_SEPAPRIORITY, and CONSHDLR_DELAYSEPA, which influence the behaviour of SCIP
1919  * calling CONSSEPASOL.
1920  *
1921  * @subsection CONSPROP
1922  *
1923  * The CONSPROP callback is called during the subproblem processing.
1924  * It should propagate the constraints, which means that it should infer reductions in the variables' local bounds
1925  * from the current local bounds.
1926  * This technique, which is the main workhorse of constraint programming, is called "node preprocessing" in the
1927  * Integer Programming community.
1928  *
1929  * The CONSPROP callback has the following options:
1930  * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
1931  * - reducing a variable's domain (result SCIP_REDUCEDDOM)
1932  * - stating that the propagator searched, but did not find domain reductions, cutting planes, or cut constraints
1933  * (result SCIP_DIDNOTFIND)
1934  * - stating that the propagator was skipped (result SCIP_DIDNOTRUN)
1935  * - stating that the propagator was skipped, but should be called again (result SCIP_DELAYED)
1936  *
1937  * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1938  * CONSHDLR_PROPFREQ, CONSHDLR_DELAYPROP, and CONSHDLR_PROP_TIMING, which influence the behaviour of SCIP
1939  * calling CONSPROP.
1940  *
1941  * @subsection CONSRESPROP
1942  *
1943  * If the constraint handler should support \ref CONF "conflict analysis", it has to supply a CONSRESPROP method.
1944  * It also should call SCIPinferVarLbCons() or SCIPinferVarUbCons() in domain propagation instead of SCIPchgVarLb() or
1945  * SCIPchgVarUb() in order to deduce bound changes on variables.
1946  * In the SCIPinferVarLbCons() and SCIPinferVarUbCons() calls, the handler provides the constraint that deduced the
1947  * variable's bound change, and an integer value <code>inferinfo</code> that can be arbitrarily chosen.
1948  *
1949  * The propagation conflict resolving method CONSRESPROP must then be implemented to provide the "reasons" for the bound
1950  * changes, i.e., the bounds of variables at the time of the propagation, which forced the constraint to set the
1951  * conflict variable's bound to its current value. It can use the <code>inferinfo</code> tag to identify its own propagation rule
1952  * and thus identify the "reason" bounds. The bounds that form the reason of the assignment must then be provided by
1953  * calls to SCIPaddConflictLb() and SCIPaddConflictUb() in the propagation conflict resolving method.
1954  *
1955  * <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
1956  * need more information to efficiently infer the original propagation steps that lead to the conflict. This would,
1957  * however, require too much space. In the extreme, the original propagation steps have to be repeated.
1958  *
1959  * 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
1960  * 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
1961  * variables are 0.0). It uses <code>SCIPinferVarLbCons(scip, z, 1.0, c, 0)</code> to apply this assignment (an
1962  * inference information tag is not needed by the constraint handler and is set to 0). In the conflict analysis, the
1963  * constraint handler may be asked to resolve the lower bound change on \f$z\f$ with constraint \f$c\f$, that was
1964  * applied at a time given by a bound change index "bdchgidx". With a call to <code>SCIPvarGetLbAtIndex(z,
1965  * bdchgidx)</code>, the handler can find out, that the lower bound of variable \f$z\f$ was set to 1.0 at the given
1966  * point of time, and should call <code>SCIPaddConflictUb(scip, x, bdchgidx)</code> and <code>SCIPaddConflictUb(scip, y,
1967  * 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
1968  * the deduction of the lower bound of \f$z\f$.
1969  *
1970  * If conflict analysis should not be supported, the method has to set the result code to SCIP_DIDNOTFIND. Although
1971  * this is a viable approach to circumvent the implementation of the usually rather complex conflict resolving method, it
1972  * will make the conflict analysis less effective. We suggest to first omit the conflict resolving method and check how
1973  * effective the \ref CONSPROP "propagation method" is. If it produces a lot of propagations for your application, you definitely should
1974  * consider implementing the conflict resolving method.
1975  *
1976  * @subsection CONSPRESOL
1977  *
1978  * The CONSPRESOL callback is called during preprocessing.
1979  * It should try to tighten the domains of the variables, tighten the coefficients of the constraints of the constraint
1980  * handler, delete redundant constraints, aggregate and fix variables if possible, and upgrade constraints to more
1981  * specific types.
1982  *
1983  * If the CONSPRESOL callback applies changes to the constraint data, you also have to implement the \ref CONSTRANS callback
1984  * in order to copy the constraint data to the transformed problem space and protect the original problem from the
1985  * preprocessing changes.
1986  *
1987  * To inform SCIP that the presolving method found a reduction the result pointer has to be set in a proper way.
1988  * The following options are possible:
1989  *
1990  * - SCIP_UNBOUNDED : at least one variable is not bounded by any constraint in objective direction
1991  * - SCIP_CUTOFF : at least one constraint is infeasible in the variable's bounds
1992  * - SCIP_SUCCESS : the presolver found a reduction
1993  * - SCIP_DIDNOTFIND : the presolver searched, but did not find a presolving change
1994  * - SCIP_DIDNOTRUN : the presolver was skipped
1995  * - SCIP_DELAYED : the presolver was skipped, but should be called again
1996  *
1997  * Please see also the @ref CONS_ADDITIONALPROPERTIES section to learn about the properties
1998  * CONSHDLR_MAXPREROUNDS and CONSHDLR_DELAYPRESOL, which influence the behaviour of SCIP
1999  * calling CONSPRESOL.
2000  *
2001  * @subsection CONSACTIVE
2002  *
2003  * The CONSACTIVE callback method is called each time a constraint of the constraint handler is activated.
2004  * For example, if a constraint is added locally to a subproblem, the CONSACTIVE callback is called whenever the
2005  * search enters the subtree where the constraint exists.
2006  *
2007  * @subsection CONSDEACTIVE
2008  *
2009  * The CONSDEACTIVE callback method is called each time a constraint of the constraint handler is deactivated.
2010  * For example, if a constraint is added locally to a subproblem, the CONSDEACTIVE callback is called whenever the
2011  * search leaves the subtree where the constraint exists.
2012  *
2013  * @subsection CONSENABLE
2014  *
2015  * The CONSENABLE callback method is called each time a constraint of the constraint handler is enabled.
2016  * Constraints might be active without being enabled. In this case, only the feasibility checks are executed,
2017  * but domain propagation and separation is skipped.
2018  *
2019  * @subsection CONSDISABLE
2020  *
2021  * The CONSDISABLE callback method is called each time a constraint of the constraint handler is disabled.
2022  *
2023  * @subsection CONSPRINT
2024  *
2025  * The CONSPRINT callback method is called, when the user asks SCIP to display the problem to the screen
2026  * or save the problem into a file. This is, however, only the case if the user requested the CIP format.
2027  * For more details about reading and writing with SCIP we refer to the \ref READER "file readers". In this
2028  * callback method the constraint handler should display the data of the constraint in an appropriate form.
2029  * The output format that is defined by the CONSPRINT callbacks is called CIP format.
2030  * In later versions of SCIP, the constraint handlers should also be able to parse (i.e., read) constraints
2031  * which are given in CIP format.
2032  *
2033  * @subsection CONSCOPY
2034  *
2035  * The CONSCOPY callback method is used whenever constraints should be copied from one SCIP instance into another SCIP
2036  * instance. This method comes with the necessary parameters to do so, most importantly with a mapping of the variables of the
2037  * source SCIP instance to the corresponding variables of the target SCIP instance, and a mapping for the constraints
2038  * in the same way. For a complete list of all arguments of this callback method see type_cons.h.
2039  *
2040  * To get the corresponding target variable of a given source variable, you can use the variable map directly:
2041  *
2042  * \code
2043  * targetvar = (SCIP_VAR*) (size_t) SCIPhashmapGetImage(varmap, sourcevar);
2044  * \endcode
2045  *
2046  * We recommend, however, to use the method SCIPgetVarCopy() which gets besides others the variable map and the constraint map as input
2047  * and returns the requested target variable. The advantage of using SCIPgetVarCopy() is that in the case
2048  * the required variable does not yet exist, it is created and added to the copy automatically:
2049  *
2050  * \code
2051  * SCIP_CALL( SCIPgetVarCopy(sourcescip, scip, sourcevar, &targetvar, varmap, consmap, global) );
2052  * \endcode
2053  *
2054  * Finally, the result pointer <code>valid</code> has to be set to TRUE if (and only if!) the copy process was successful.
2055  *
2056  * <b>Note:</b> Be careful when setting the valid pointer. If you set the valid pointer to TRUE, but the constraint was
2057  * not copied one-to-one, then optimal solutions might be cut off during the search (see section
2058  * CONSHDLRCOPY above).
2059  *
2060  * For an example implementation we refer to cons_linear.h. Additional documentation and the complete list of all
2061  * parameters can be found in the file in type_cons.h.
2062  *
2063  * @subsection CONSPARSE
2064  *
2065  * This method is the counter part to CONSPRINT. The ideal idea is that a constraint handler is able to parse the output
2066  * which it generated via the CONSPRINT method and creates the corresponding constraint. If the parsing was successfully
2067  * the result pointer success should be set to TRUE. An example implementation can be found in the \ref cons_linear.h
2068  * "linear constraint handler".
2069  *
2070  * @subsection CONSDELVARS
2071  *
2072  * This method should iterate over the given constraints and delete all variables that were marked for deletion by SCIPdelVar().
2073  * Variable deletion is especially interesting for branch-cut-and-price applications. If your constraint handler allows
2074  * the addition of variables during the solving process (see "modifiable" attribute of constraints), then you might also want to
2075  * implement this callback. This would allow you to not only create variables during solving, but also remove them dynamically
2076  * from the problem to reduce memory consumption in case they are no longer necessary.
2077  * During presolving, SCIP may also find that some variables are not needed anymore and then try
2078  * to delete them. Thus, if you do not implement this callback, the constraint handler should capture its variables via
2079  * SCIPcaptureVar() to prevent SCIP from erroneously deleting them.
2080  *
2081  * Additional documentation and the complete list of all parameters can be found in the file type_cons.h.
2082  *
2083  * @subsection CONSGETVARS
2084  *
2085  * The CONSGETVARS callback of a constraint handler can be implemented to give access to the constraint variables
2086  * as array, independently from the internal data structure of the constraint. The buffer array
2087  * is already passed, together with its length. Consider implementing @ref CONSGETNVARS, too, to have
2088  * information about the number of variables in this constraint.
2089  *
2090  * @subsection CONSGETNVARS
2091  *
2092  * This callback can be implemented to return the number of variables involved into a particular constraint.
2093  * In order to have access to the variable pointers, consider implementing @ref CONSGETVARS.
2094  *
2095  * @section CONS_FURTHERINFO Further documentation
2096  *
2097  * Further documentation can be found in @ref type_cons.h for callback descriptions and a complete
2098  * list of all callback parameters, or in @ref scip.h
2099  * for globally available functions.
2100  */
2101 
2102 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2103 /**@page PRICER How to add variable pricers
2104  *
2105  * A pricer performs the dynamic generation of new variables in a column generation algorithm.
2106  * It is an algorithmic representation of a (usually exponential) number of variables.
2107  * The \ref PRICERREDCOST and \ref PRICERFARKAS methods are called after each LP solve to generate additional
2108  * variables which may improve the objective value or decrease the LP infeasibility, respectively.
2109  * \n
2110  * A complete list of all pricers contained in this release can be found \ref PRICERS "here".
2111  *
2112  * If the pricer finds one or more variables with negative reduced costs or negative Farkas value, it should
2113  * call SCIPcreateVar() and SCIPaddPricedVar() to create and add the variable to the problem. Additionally,
2114  * the pricer has to add the variable to all constraints in which it appears. Therefore, a pricer needs to
2115  * know the constraints of the model and their meaning. Note that all constraints for which additional variables
2116  * are generated by a pricer have to be flagged as "modifiable" in the SCIPcreateCons() call.
2117  *
2118  * We now explain how users can add their own pricers.
2119  * For example, look into the stable set pricer for the coloring problem (examples/Coloring/src/pricer_coloring.c) of the
2120  * Coloring example project.
2121  * The example is written in C. C++ users can easily adapt the code by using the scip::scip::ObjPricer wrapper base class and
2122  * implement the scip_...() virtual methods instead of the SCIP_DECL_PRICER... callback methods.
2123  *
2124  * Additional documentation for the callback methods of a pricer can be found in the file
2125  * type_pricer.h.
2126  *
2127  * Notice that if your pricer cannot cope with variable bounds other than 0 and infinity, you have to mark
2128  * all constraints containing priced variables as modifiable, and you may have to disable reduced cost
2129  * strengthening by setting propagating/rootredcost/freq to -1.
2130  *
2131  * Here is what you have to do to implement a pricer:
2132  * -# Copy the template files src/scip/pricer_xyz.c and src/scip/pricer_xyz.h into files "pricer_mypricer.c"
2133  * and "pricer_mypricer.h".
2134  * \n
2135  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
2136  * -# Use SCIPincludePricerMypricer() in order to include the pricer into your SCIP instance,
2137  * e.g., in the main file of your project (see, e.g., src/main.c in the Coloring example).
2138  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypricer".
2139  * -# Adjust the properties of the pricer (see \ref PRICER_PROPERTIES).
2140  * -# Define the pricer data (see \ref PRICER_DATA). This is optional.
2141  * -# Implement the interface methods (see \ref PRICER_INTERFACE).
2142  * -# Implement the fundamental callback methods (see \ref PRICER_FUNDAMENTALCALLBACKS).
2143  * -# Implement the additional callback methods (see \ref PRICER_ADDITIONALCALLBACKS). This is optional.
2144  *
2145  *
2146  * @section PRICER_PROPERTIES Properties of a Pricer
2147  *
2148  * At the top of the new file "pricer_mypricer.c" you can find the pricer properties.
2149  * These are given as compiler defines.
2150  * In the C++ wrapper class, you have to provide the pricer properties by calling the constructor
2151  * of the abstract base class scip::ObjPricer from within your constructor.
2152  * The properties you have to set have the following meaning:
2153  *
2154  * \par PRICER_NAME: the name of the pricer.
2155  * This name is used in the interactive shell to address the pricer.
2156  * Additionally, if you are searching for a pricer with SCIPfindPricer(), this name is looked up.
2157  * Names have to be unique: no two pricers may have the same name.
2158  *
2159  * \par PRICER_DESC: the description of the pricer.
2160  * This string is printed as a description of the pricer in the interactive shell.
2161  *
2162  * \par PRICER_PRIORITY: the priority of the pricer.
2163  * In each pricing round during the price-and-cut loop of the subproblem processing, the included pricers are
2164  * called in a predefined order, which is given by the priorities of the pricers.
2165  * The higher the priority, the earlier the pricer is called.
2166  * Usually, you will have only one pricer in your application and the priority is therefore irrelevant.
2167  *
2168  * \par PRICER_DELAY: the default for whether the pricer should be delayed, if other variables with negative reduced
2169  * costs have already been found in the current pricing round.
2170  * Variables may be declared to be "removable" in the SCIPcreateVar() call. This means that SCIP may remove the variable
2171  * from the LP if it was inactive (i.e., sitting at zero) for a number of LP solves. Nevertheless, after the removal of the
2172  * column from the LP, the variable still exists, and SCIP can calculate reduced costs and add it to the LP again if
2173  * necessary.
2174  * \n
2175  * If the PRICER_DELAY flag is set to TRUE (which is the common setting), all those existing variables with negative reduced costs
2176  * are added to the LP, and the LP is resolved before the pricer is called. Thus, the pricer can assume that all existing variables
2177  * have non-negative reduced costs if the \ref PRICERREDCOST method is called or non-positive Farkas value if the \ref PRICERFARKAS
2178  * method is called.
2179  * \n
2180  * In some applications, this inner pricing loop on the already existing variables can significantly slow down the solving process,
2181  * since it may lead to the addition of only very few variables in each pricing round. If this is an issue in your application,
2182  * you should consider setting the PRICER_DELAY flag to FALSE. You must, however, be aware of the fact that there may be already
2183  * existing variables with negative reduced costs. For example, this may lead to the issue that your pricer generates the same
2184  * variable twice. In some models, this is not critical because an optimal solution would choose only one of the two identical
2185  * variables anyway, but for other models this can lead to wrong results because the duplication of a variable essentially doubles
2186  * the upper bound of the variable.
2187  *
2188  *
2189  * @section PRICER_DATA Pricer Data
2190  *
2191  * Below the header "Data structures" you can find a struct which is called "struct SCIP_PricerData".
2192  * In this data structure, you can store the data of your pricer. For example, it may be convenient to store pointers to the
2193  * constraints of the problem instance here, because the pricer has to add variables to those constraints.
2194  * If you are using C++, you can add pricer data, as usual, as object variables to your class.
2195  * \n
2196  * Defining pricer data is optional. You can leave the struct empty.
2197  *
2198  *
2199  * @section PRICER_INTERFACE Interface Methods
2200  *
2201  * At the bottom of "pricer_mypricer.c" you can find the interface method SCIPincludePricerMypricer(), which also appears in "pricer_mypricer.h".
2202  * It is called by the user, if (s)he wants to include the pricer, i.e., if (s)he wants to solve a model for which variables should
2203  * be generated by this pricer.
2204  *
2205  * This method only has to be adjusted slightly.
2206  * It is responsible for notifying SCIP of the presence of the pricer. For this, you can either call SCIPincludePricer(),
2207  * or SCIPincludePricerBasic() since SCIP version 3.0. In the latter variant, \ref PRICER_ADDITIONALCALLBACKS "additional callbacks"
2208  * must be added via setter functions as, e.g., SCIPsetPricerCopy(). We recommend this latter variant because
2209  * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2210  * variant must be manually adjusted with every SCIP release containing new callbacks for pricers in order to compile.
2211  *
2212  *
2213  * In addition, the pricer has to be activated before the solution process starts, like it is done
2214  * in the reader of the Coloring example (examples/Coloring/src/reader_col.c) by calling
2215  * \code
2216  * SCIP_CALL( SCIPactivatePricer(scip, SCIPfindPricer(scip, "coloring")) );
2217  * \endcode
2218  *
2219  * If you are using pricer data, you have to allocate the memory for the data at this point.
2220  * You can do this by calling:
2221  * \code
2222  * SCIP_CALL( SCIPallocMemory(scip, &pricerdata) );
2223  * \endcode
2224  * You also have to initialize the fields in struct SCIP_PricerData afterwards.
2225  *
2226  * You may also add user parameters for your pricer, see the method SCIPincludePricerColoring() in the pricer of the Coloring example
2227  * for an example of how to add user parameters.
2228  *
2229  *
2230  * @section PRICER_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Pricer
2231  *
2232  * The fundamental callback methods have to be implemented in order to obtain an operational algorithm.
2233  * They are passed together with the pricer itself to SCIP using SCIPincludePricer() or SCIPincludePricerBasic(),
2234  * see @ref PRICER_INTERFACE.
2235  *
2236  * In the case of a pricer, there are two fundamental callback methods, namely the @ref PRICERREDCOST and the
2237  * @ref PRICERFARKAS callbacks, which both search for new variables and add them to the problem.
2238  * These methods have to be implemented for every pricer; the other callback methods are optional.
2239  * In the C++ wrapper class scip::ObjPricer, the scip_redcost() method (which corresponds to the PRICERREDCOST callback)
2240  * is a virtual abstract member function. You have to implement it in order to be able to construct an object of your
2241  * pricer class.
2242  *
2243  * Additional documentation for the callback methods can be found in type_pricer.h.
2244  *
2245  * @subsection PRICERREDCOST
2246  *
2247  * The PRICERREDCOST callback is called inside the price-and-cut loop of the subproblem solving process if the current LP relaxation
2248  * is feasible.
2249  * It should search for additional variables that can contribute to improve the current LP's solution value.
2250  * In standard branch-and-price, these are variables with negative dual feasibility, that is negative
2251  * reduced costs for non-negative variables, positive reduced costs for non-positive variables,
2252  * and non-zero reduced costs for variables that can be negative and positive.
2253  *
2254  * Whenever the pricer finds a variable with negative dual feasibility, it should call SCIPcreateVar()
2255  * and SCIPaddPricedVar() to add the variable to the problem. Furthermore, it should call the appropriate
2256  * methods of the constraint handlers to add the necessary variable entries to the constraints, see pub_cons.h.
2257  *
2258  * In the usual case that the pricer either adds a new variable or ensures that there are no further variables with negative dual feasibility,
2259  * the result pointer should be set to SCIP_SUCCESS. Only if the pricer aborts pricing without creating a new variable, but
2260  * there might exist additional variables with negative dual feasibility, the result pointer should be set to SCIP_DIDNOTRUN.
2261  * In this case, which sometimes is referred to as "early branching", the LP solution will not be used as a lower bound.
2262  * The pricer can, however, store a valid lower bound in the <code>lowerbound</code> pointer.
2263  *
2264  * Pricers usually need the dual LP solution as input for the pricing algorithm.
2265  * Since SCIP does not know the semantics of the individual constraints in the problem, the dual solution
2266  * has to be provided by the constraint handlers.
2267  * For example, the \ref cons_setppc.h "setppc constraint handler", which deals with set partitioning, packing, and covering constraints, provides
2268  * the method SCIPgetDualsolSetppc() to access the dual solution value for a single constraint.
2269  * Similarly, the dual solution of a linear constraint can be queried with the method SCIPgetDualsolLinear() of cons_linear.h.
2270  * The reduced costs of the existing variables can be accessed with the method SCIPgetVarRedcost().
2271  *
2272  * @subsection PRICERFARKAS
2273  *
2274  * If the current LP relaxation is infeasible, it is the task of the pricer to generate additional variables that can
2275  * potentially render the LP feasible again. In standard branch-and-price, these are variables with positive Farkas values,
2276  * and the PRICERFARKAS method should identify those variables.
2277  *
2278  * If the LP was proven to be infeasible, we have an infeasibility proof by the dual Farkas multipliers \f$y\f$.
2279  * With the values of \f$y\f$, an implicit inequality \f$y^T A x \ge y^T b\f$ is associated, with \f$b\f$ given
2280  * by the sides of the LP rows and the sign of \f$y\f$:
2281  * - if \f$y_i\f$ is positive, \f$b_i\f$ is the left hand side of the row,
2282  * - if \f$y_i\f$ is negative, \f$b_i\f$ is the right hand side of the row.
2283  *
2284  * \f$y\f$ is chosen in a way, such that the valid inequality \f$y^T A x \ge y^T b\f$ is violated by all \f$x\f$,
2285  * especially by the (for this inequality least infeasible solution) \f$x'\f$ defined by
2286  * - \f$x'_i := ub_i\f$, if \f$y^T A_i \ge 0\f$
2287  * - \f$x'_i := lb_i\f$, if \f$y^T A_i < 0\f$.
2288  * Pricing in this case means to add variables \f$i\f$ with positive Farkas value, i.e., \f$y^T A_i x'_i > 0\f$.
2289  *
2290  * To apply Farkas pricing, the pricer needs to know the Farkas values of the constraints. Like the dual solution values for
2291  * feasible LP solutions, the dual Farkas values for infeasible solutions can be obtained by constraint handler interface
2292  * methods such as the SCIPgetDualfarkasLinear() method of the linear constraint handler.
2293  * The Farkas values for the bounds of the variables are just the regular reduced costs and can be accessed with SCIPgetVarRedcost().
2294  *
2295  * It is useful to note that Farkas pricing is the same as the regular pricing with a zero objective function.
2296  * Therefore, a typical implementation of a pricer would consist of a generic pricing algorithm that gets a dual solution and an
2297  * objective function vector as input and generates variables by calling SCIPcreateVar() and SCIPaddPricedVar().
2298  * The PRICERREDCOST callback would call this function with the regular objective function and the regular dual solution vector,
2299  * while the PRICERFARKAS callback would call this function with a zero objective function and the Farkas vector.
2300  * From a practical point of view, it is usually the simplest approach to provide just one Boolean flag to the generic pricing
2301  * algorithm in order to identify whether it is reduced cost or Farkas pricing. Then, the algorithm would just call the appropriate
2302  * methods to access the dual solution or objective function, depending on the Boolean flag.
2303  *
2304  * @section PRICER_ADDITIONALCALLBACKS Additional Callback Methods of a Pricer
2305  *
2306  * The additional callback methods do not need to be implemented in every case.
2307  * However, some of them have to be implemented for most applications. They can either be passed directly with
2308  * SCIPincludePricer() to SCIP or via specific <b>setter functions</b> after a call of SCIPincludePricerBasic(),
2309  * see also @ref PRICER_INTERFACE.
2310  *
2311  * @subsection PRICERFREE
2312  *
2313  * If you are using pricer data, you have to implement this method in order to free the pricer data.
2314  * This can be done by the following procedure:
2315  * \code
2316  * static
2317  * SCIP_DECL_PRICERFREE(pricerFreeMypricer)
2318  * {
2319  * SCIP_PRICERDATA* pricerdata;
2320  *
2321  * pricerdata = SCIPpricerGetData(pricer);
2322  * assert(pricerdata != NULL);
2323  *
2324  * SCIPfreeMemory(scip, &pricerdata);
2325  *
2326  * SCIPpricerSetData(pricer, NULL);
2327  *
2328  * return SCIP_OKAY;
2329  * }
2330  * \endcode
2331  * If you have allocated memory for fields in your pricer data, remember to free this memory
2332  * before freeing the pricer data itself.
2333  * If you are using the C++ wrapper class, this method is not available.
2334  * Instead, just use the destructor of your class to free the member variables of your class.
2335  *
2336  * @subsection PRICERCOPY
2337  *
2338  * The PRICERCOPY callback is executed when the SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
2339  * callback as <code>NULL</code> the user disables the inclusion of the pricer into all copied SCIP
2340  * instances. This means that primal heuristics will work on a sub-SCIP that contains only a part of the variables
2341  * and no variables are priced in during the solving process of the sub-SCIP. Therefore, primal solutions found in the
2342  * copied problem are typically still valid for the original problem and used for its solving process,
2343  * but dual reductions cannot be transferred to the original problem.
2344  *
2345  * <b>Note:</b> If you implement this callback, be careful when setting the valid pointer. The valid pointer should be
2346  * set to TRUE if (and only if!) you can make sure that all necessary data of the pricer are copied
2347  * correctly. If the complete problem is validly copied, i.e. if the copy methods of all problem defining plugins
2348  * (constraint handlers and pricers) return <code>*valid = TRUE</code>, then dual reductions found for the copied problem can be
2349  * transferred to the original SCIP instance. Thus, if the valid pointer is wrongly set to TRUE, it might happen that
2350  * optimal solutions are cut off.
2351  *
2352  * @subsection PRICERINIT
2353  *
2354  * The PRICERINIT callback is executed after the problem is transformed.
2355  * The pricer may, e.g., use this call to replace the original constraints stored in its pricer data by transformed
2356  * constraints, or to initialize other elements of its pricer data.
2357  *
2358  * @subsection PRICEREXIT
2359  *
2360  * The PRICEREXIT callback is executed before the transformed problem is freed.
2361  * In this method, the pricer should free all resources that have been allocated for the solving process in PRICERINIT.
2362  *
2363  * @subsection PRICERINITSOL
2364  *
2365  * The PRICERINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to begin.
2366  * The pricer may use this call to initialize its branch-and-bound specific data.
2367  *
2368  * @subsection PRICEREXITSOL
2369  *
2370  * The PRICEREXITSOL callback is executed before the branch-and-bound process is freed.
2371  * The pricer should use this call to clean up its branch-and-bound data, which was allocated in PRICERINITSOL.
2372  *
2373  * @section PRICER_REMARKS Further remarks
2374  *
2375  * If you use your own branching rule (e.g., to branch on constraints), make sure that it is able to branch on \a "pseudo solutions".
2376  * Otherwise, SCIP will use its default branching rules, if necessary (which all branch on variables). This
2377  * could disturb the pricing problem or branching might not even be possible, e.g., if all variables created thus far have already been fixed.
2378  *
2379  * Note that if the original problem is a maximization problem, SCIP will transform the problem into a minimization
2380  * problem by multiplying the objective function by -1. The pricer has to take care of this by multiplying
2381  * the original objective function value of all variables created during the solving process by -1.
2382  *
2383  * In some cases, bounds on variables are implicitly enforced by constraints of the problem and the objective function.
2384  * Therefore, these bounds do not need to be added to the LP explicitly, which has the advantage that the pricing routine does not need to
2385  * care about the corresponding dual values.
2386  * We call these bounds lazy bounds, they may be set by SCIPchgVarLbLazy() and SCIPchgVarUbLazy() for upper or lower bounds, respectively.
2387  * If the lazy bound is tighter than the local bound, the corresponding bound is not put into the LP.
2388  * In diving mode, lazy bounds are explicitly put into the LP, because changing the objective (which is only possible in diving)
2389  * might reverse the implicitly given bounds. When diving is finished, the bounds are again removed from the LP.
2390  */
2391 
2392 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2393 /**@page PRESOL How to add presolvers
2394  *
2395  * Presolvers are used to reduce the size of the model by removing irrelevant information like redundant constraints,
2396  * to strengthen the LP relaxation by exploiting integrality information, and to extract useful information in the
2397  * presolving step.
2398  * Constraint based presolving is done in the CONSPRESOL callback methods of the constraint handlers, see \ref CONSPRESOL.
2399  * The presolver plugins complement the constraint based presolving by additional, usually optimality based, presolving
2400  * reductions.
2401  * \n
2402  * A complete list of all presolvers contained in this release can be found \ref PRESOLVERS "here".
2403  *
2404  * We now explain how users can add their own presolvers.
2405  * Take the dual fixing presolver (src/scip/presol_dualfix.c) as an example.
2406  * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjPresol wrapper
2407  * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_PRESOL... callback methods.
2408  *
2409  * Additional documentation for the callback methods of a presolver, in particular for their input parameters,
2410  * can be found in the file type_presol.h.
2411  *
2412  * Here is what you have to do to implement a presolver:
2413  * -# Copy the template files src/scip/presol_xyz.c and src/scip/presol_xyz.h into files named "presol_mypresolver.c"
2414  * and "presol_mypresolver.h".
2415  * \n
2416  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
2417  * -# Use SCIPincludePresolMypresolver() in order to include the presolver into your SCIP instance,
2418  * e.g., in the main file of your project (see, e.g., src/main.c in the Coloring example).
2419  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypresolver".
2420  * -# Adjust the properties of the presolver (see \ref PRESOL_PROPERTIES).
2421  * -# Define the presolver data (see \ref PRESOL_DATA). This is optional.
2422  * -# Implement the interface methods (see \ref PRESOL_INTERFACE).
2423  * -# Implement the fundamental callback methods (see \ref PRESOL_FUNDAMENTALCALLBACKS).
2424  * -# Implement the additional callback methods (see \ref PRESOL_ADDITIONALCALLBACKS). This is optional.
2425  *
2426  *
2427  * @section PRESOL_PROPERTIES Properties of a Presolver
2428  *
2429  * At the top of the new file "presol_mypresolver.c", you can find the presolver properties.
2430  * These are given as compiler defines.
2431  * In the C++ wrapper class, you have to provide the presolver properties by calling the constructor
2432  * of the abstract base class scip::ObjPresol from within your constructor.
2433  * The properties you have to set have the following meaning:
2434  *
2435  * \par PRESOL_NAME: the name of the presolver.
2436  * This name is used in the interactive shell to address the presolver.
2437  * Additionally, if you are searching for a presolver with SCIPfindPresol(), this name is looked up.
2438  * Names have to be <b>unique</b>: no two presolvers may have the same name.
2439  *
2440  * \par PRESOL_DESC: the description of the presolver.
2441  * This string is printed as a description of the presolver in the interactive shell.
2442  *
2443  * \par PRESOL_PRIORITY: the priority of the presolver.
2444  * In each presolving round, the presolvers and presolving methods of the constraint handlers are called in
2445  * a predefined order, which is given by the priorities of the presolvers and the check priorities of the
2446  * constraint handlers, see \ref CONS_PROPERTIES.
2447  * First, the presolvers with non-negative priority are called in the order of decreasing priority.
2448  * Next, the presolving methods of the different constraint handlers are called in the order of decreasing check
2449  * priority.
2450  * Finally, the presolvers with negative priority are called in the order of decreasing priority.
2451  * \n
2452  * The priority of the presolver should be set according to the complexity of the presolving algorithm and the impact of the reduction:
2453  * presolvers that provide fast algorithms that usually have a high impact (i.e., remove lots of variables or tighten
2454  * bounds of many variables) should have a high priority. An easy way to list the
2455  * priorities of all presolvers and constraint handlers is to type "display presolvers" and "display conshdlrs" in
2456  * the interactive shell of SCIP.
2457  *
2458  * \par PRESOL_MAXROUNDS: the default maximal number of rounds the presolver participates in.
2459  * The presolving is conducted in rounds: the presolvers and presolving methods of the constraint handlers
2460  * are called iteratively until no more reductions have been found or some other abort criterion applies.
2461  * The "maxrounds" parameter of a presolver imposes a limit on the number of presolving rounds in which the
2462  * presolver is called. The PRESOL_MAXROUNDS property specifies the default value for this parameter.
2463  * A value of -1 represents an unlimited number of rounds.
2464  *
2465  * \par PRESOL_DELAY: the default for whether the presolver should be delayed, if other presolvers found reductions.
2466  * If the presolver is marked to be delayed, it is only executed if no other presolvers found a reduction during the current
2467  * presolving round.
2468  * If the presolver is very expensive, you may want to mark it to be delayed until all cheap presolving methods have been executed.
2469  *
2470  *
2471  * @section PRESOL_DATA Presolver Data
2472  *
2473  * Below the header "Data structures" you can find a struct which is called "struct SCIP_PresolData".
2474  * In this data structure, you can store the data of your presolver. For example, you should store the adjustable parameters
2475  * of the presolver in this data structure.
2476  * If you are using C++, you can add presolver data as usual as object variables to your class.
2477  * \n
2478  * Defining presolver data is optional. You can leave this struct empty.
2479  *
2480  *
2481  * @section PRESOL_INTERFACE Interface Methods
2482  *
2483  * At the bottom of "presol_mypresolver.c", you can find the interface method SCIPincludePresolMypresolver(),
2484  * which also appears in "presol_mypresolver.h"
2485  * SCIPincludePresolMypresolver() is called by the user, if (s)he wants to include the presolver,
2486  * i.e., if (s)he wants to use the presolver in his/her application.
2487  *
2488  * This method only has to be adjusted slightly.
2489  * It is responsible for notifying SCIP of the presence of the presolver. For this, you can either call SCIPincludePresol(),
2490  * or SCIPincludePresolBasic() since SCIP version 3.0. In the latter variant, \ref PRESOL_ADDITIONALCALLBACKS "additional callbacks"
2491  * must be added via setter functions as, e.g., SCIPsetPresolCopy(). We recommend this latter variant because
2492  * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2493  * variant must be manually adjusted with every SCIP release containing new callbacks for presolvers in order to compile.
2494  *
2495  * If you are using presolver data, you have to allocate the memory for the data at this point.
2496  * You can do this by calling:
2497  * \code
2498  * SCIP_CALL( SCIPallocMemory(scip, &presoldata) );
2499  * \endcode
2500  * You also have to initialize the fields in struct SCIP_PresolData afterwards. For freeing the
2501  * presolver data, see \ref PRESOLFREE.
2502  *
2503  * You may also add user parameters for your presolver, see \ref PARAM for how to add user parameters and
2504  * the method SCIPincludePresolTrivial() in src/scip/presol_trivial.c for an example.
2505  *
2506  *
2507  * @section PRESOL_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Presolver
2508  *
2509  * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2510  * an operational algorithm.
2511  * They are passed together with the presolver itself to SCIP using SCIPincludePresol() or SCIPincludePresolBasic(),
2512  * see @ref PRESOL_INTERFACE.
2513  *
2514  * Presolver plugins have only one fundamental callback method, namely the @ref PRESOLEXEC method.
2515  * This method has to be implemented for every presolver; the other callback methods are optional.
2516  * In the C++ wrapper class scip::ObjPresol, the scip_exec() method (which corresponds to the PRESOLEXEC callback) is a virtual
2517  * abstract member function.
2518  * You have to implement it in order to be able to construct an object of your presolver class.
2519  *
2520  * Additional documentation for the callback methods, in particular to their input parameters,
2521  * can be found in type_presol.h.
2522  *
2523  * @subsection PRESOLEXEC
2524  *
2525  * The PRESOLEXEC callback is called inside the presolving loop and should perform the actual presolving reductions.
2526  * It should inspect the problem instance at hand and simplify it by tightening bounds of variables, aggregating or fixing
2527  * variables, changing the type of variables, modifying the graph that represents the instance of your application, and
2528  * the like.
2529  *
2530  * Typical methods called by a presolver are, for example, SCIPchgVarType(), SCIPfixVar(), SCIPaggregateVars(), SCIPtightenVarLb(),
2531  * and SCIPtightenVarUb().
2532  *
2533  *
2534  * @section PRESOL_ADDITIONALCALLBACKS Additional Callback Methods of a Presolver
2535  *
2536  * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2537  * implemented for most applications, they can be used, for example, to initialize and free private data.
2538  * Additional callbacks can either be passed directly with SCIPincludePresol() to SCIP or via specific
2539  * <b>setter functions</b> after a call of SCIPincludePresolBasic(), see also @ref PRESOL_INTERFACE.
2540  *
2541  * @subsection PRESOLFREE
2542  *
2543  * 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.
2544  * This can be done by the following procedure:
2545  * \code
2546  * static
2547  * SCIP_DECL_PRESOLFREE(presolFreeMypresolver)
2548  * {
2549  * SCIP_PRESOLDATA* presoldata;
2550  *
2551  * presoldata = SCIPpresolGetData(presol);
2552  * assert(presoldata != NULL);
2553  *
2554  * SCIPfreeMemory(scip, &presoldata);
2555  *
2556  * SCIPpresolSetData(presol, NULL);
2557  *
2558  * return SCIP_OKAY;
2559  * }
2560  * \endcode
2561  * If you have allocated memory for fields in your presolver data, remember to free this memory
2562  * before freeing the presolver data itself.
2563  * If you are using the C++ wrapper class, this method is not available.
2564  * Instead, just use the destructor of your class to free the member variables of your class.
2565  *
2566  * @subsection PRESOLINIT
2567  *
2568  * The PRESOLINIT callback is executed after the problem is transformed.
2569  * The presolver may, e.g., use this call to initialize its presolver data.
2570  * The difference between the original and the transformed problem is explained in
2571  * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
2572  *
2573  * @subsection PRESOLCOPY
2574  *
2575  * The PRESOLCOPY callback is executed when a SCIP instance is copied, e.g. to
2576  * solve a sub-SCIP. By
2577  * defining this callback as
2578  * <code>NULL</code> the user disables the execution of the specified
2579  * presolver for all copied SCIP instances. This may deteriorate the performance
2580  * of primal heuristics using sub-SCIPs.
2581  *
2582  * @subsection PRESOLEXIT
2583  *
2584  * The PRESOLEXIT callback is executed before the transformed problem is freed.
2585  * In this method, the presolver should free all resources that have been allocated for the solving process in PRESOLINIT.
2586  *
2587  * @subsection PRESOLINITPRE
2588  *
2589  * The PRESOLINITPRE callback is executed when the presolving is about to begin.
2590  * The presolver may use this call to initialize its presolving data which only need to exist during the presolving stage.
2591  *
2592  * @subsection PRESOLEXITPRE
2593  *
2594  * The PRESOLEXITPRE callback is executed after presolving finishes and before the branch-and-bound process begins.
2595  * The presolver should use this call to clean up its presolving data, which was allocated in PRESOLINITPRE.
2596  */
2597 
2598 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2599 /**@page SEPA How to add separators
2600  *
2601  * Separators are used to generate general purpose cutting planes.
2602  * Constraint based cutting planes, the second type of cutting planes in SCIP, are separated in the CONSSEPALP and
2603  * CONSSEPASOL callback methods of the constraint handlers, see \ref CONSSEPALP and \ref CONSSEPASOL. These cuts are
2604  * valid inequalities or even facets of the polyhedron described by a single constraint or a subset of the constraints of
2605  * a single constraint class. In contrast, general purpose cuts do not require or exploit any knowledge about the
2606  * underlying problem structure but use only the current LP relaxation and the integrality conditions. See also
2607  * "When should I implement a constraint handler, when should I implement a separator?" on \ref FAQ.
2608  * \n
2609  * A complete list of all separators contained in this release can be found \ref SEPARATORS "here".
2610  *
2611  * We now explain how users can add their own separators.
2612  * Take the separator for the class of Gomory mixed integer inequalities (src/scip/sepa_gomory.c) as an example.
2613  * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjSepa wrapper
2614  * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_SEPA... callback methods.
2615  *
2616  * Additional documentation for the callback methods of a separator, in particular for the input parameters,
2617  * can be found in the file type_sepa.h.
2618  *
2619  * Here is what you have to do to implement a separator:
2620  * -# Copy the template files src/scip/sepa_xyz.c and src/scip/sepa_xyz.h into files "sepa_myseparator.c"
2621  * and "sepa_myseparator.h".
2622  \n
2623  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
2624  * -# Use SCIPincludeSepaMyseparator() in order to include the separator into your SCIP instance,
2625  * e.g., in the main file of your project (see, e.g., src/main.c in the Coloring example).
2626  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myseparator".
2627  * -# Adjust the properties of the separator (see \ref SEPA_PROPERTIES).
2628  * -# Define the separator data (see \ref SEPA_DATA). This is optional.
2629  * -# Implement the interface methods (see \ref SEPA_INTERFACE).
2630  * -# Implement the fundamental callback methods (see \ref SEPA_FUNDAMENTALCALLBACKS).
2631  * -# Implement the additional callback methods (see \ref SEPA_ADDITIONALCALLBACKS). This is optional.
2632  *
2633  *
2634  * @section SEPA_PROPERTIES Properties of a Separator
2635  *
2636  * At the top of the new file "sepa_myseparator.c", you can find the separator properties.
2637  * These are given as compiler defines.
2638  * In the C++ wrapper class, you have to provide the separator properties by calling the constructor
2639  * of the abstract base class scip::ObjSepa from within your constructor.
2640  * The properties you have to set have the following meaning:
2641  *
2642  * \par SEPA_NAME: the name of the separator.
2643  * This name is used in the interactive shell to address the separator.
2644  * Additionally, if you are searching for a separator with SCIPfindSepa(), this name is looked up.
2645  * Names have to be unique: no two separators may have the same name.
2646  *
2647  * \par SEPA_DESC: the description of the separator.
2648  * This string is printed as a description of the separator in the interactive shell.
2649  *
2650  * \par SEPA_PRIORITY: the priority of the separator.
2651  * In each separation round during the price-and-cut loop of the subproblem processing or the separation loop
2652  * of the primal solution separation, the separators and separation methods of the constraint handlers are called in
2653  * a predefined order, which is given by the priorities of the separators and the separation priorities
2654  * of the constraint handlers (see \ref CONS_PROPERTIES).
2655  * First, the separators with non-negative priority are called in the order of decreasing priority.
2656  * Next, the separation methods of the constraint handlers are called in the order of decreasing separation
2657  * priority.
2658  * Finally, the separators with negative priority are called in the order of decreasing priority. An easy way to list the
2659  * priorities of all separators and constraint handlers is to type "display separators" and "display conshdlrs" in
2660  * the interactive shell.
2661  * \n
2662  * The priority of the separator should be set according to the complexity of the cut separation algorithm and the
2663  * impact of the resulting cuts: separators that provide fast algorithms that usually have a high impact (i.e., cut off
2664  * a large portion of the LP relaxation) should have a high priority.
2665  * See \ref SEPAEXECLP and \ref SEPAEXECSOL for further details of the separation callbacks.
2666  *
2667  * \par SEPA_FREQ: the default frequency for separating cuts.
2668  * The frequency defines the depth levels at which the separation methods \ref SEPAEXECLP and \ref SEPAEXECSOL are called.
2669  * For example, a frequency of 7 means, that the separation callback is executed for subproblems that are in depth
2670  * 0, 7, 14, ... of the branching tree. A frequency of 0 means, that the separation method is only called at the root node.
2671  * A frequency of -1 disables the separator.
2672  * \n
2673  * The frequency can be adjusted by the user. This property of the separator only defines the default value of the frequency.
2674  * If you want to have a more flexible control of when to execute the separation algorithm, you have to assign
2675  * a frequency of 1 and implement a check at the beginning of your separation methods whether you really want to execute
2676  * the separation or not. If you do not want to execute it, set the result code of
2677  * \ref SEPAEXECLP and \ref SEPAEXECSOL to SCIP_DIDNOTRUN.
2678  *
2679  * \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.
2680  * At the current branch-and-bound node, the relative distance from its dual bound (local dual bound)
2681  * to the primal bound compared to the best node's dual bound (global dual bound) is considered. The separation method
2682  * of the separator will only be applied at the current node if this relative distance does not exceed SEPA_MAXBOUNDDIST.
2683  * \n
2684  * For example, if the global dual bound is 50 and the primal bound is 60, SEPA_MAXBOUNDDIST = 0.25 means that separation
2685  * 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
2686  * than or equal to 52.5.
2687  * \n
2688  * In particular, the values 0.0 and 1.0 mean that separation is applied at the current best node only or at all
2689  * nodes, respectively. Since separation seems to be most important to apply at nodes that define to the global
2690  * dual bound, 0.0 is probably a good choice for SEPA_MAXBOUNDDIST.
2691  * Note that separators with a frequency of SEPA_FREQ = 0 are only applied at the root node.
2692  * Obviously, at the root node the local dual bound is equal to the global dual bound and thus, the separator is called
2693  * for any value of SEPA_MAXBOUNDDIST.
2694  *
2695  * \par SEPA_USESSUBSCIP: Does the separator use a secondary SCIP instance?
2696  * Some heuristics and separators solve MIPs or SAT problems and use a secondary SCIP instance. Examples are
2697  * Large Neighborhood Search heuristics such as RINS and Local Branching or the CGMIP separator. To avoid recursion,
2698  * these plugins usually deactivate all other plugins that solve MIPs. If a separator uses a secondary SCIP instance,
2699  * this parameter has to be TRUE and it is recommended to call SCIPsetSubscipsOff() for the secondary SCIP instance.
2700  *
2701  * \par SEPA_DELAY: the default for whether the separation method should be delayed, if other separators or constraint handlers found cuts.
2702  * If the separator's separation method is marked to be delayed, it is only executed after no other separator
2703  * or constraint handler found a cut during the price-and-cut loop.
2704  * If the separation method of the separator is very expensive, you may want to mark it to be delayed until all cheap
2705  * separation methods have been executed.
2706  *
2707  * @section SEPA_DATA Separator Data
2708  *
2709  * Below the header "Data structures" you can find a struct which is called "struct SCIP_SepaData".
2710  * In this data structure, you can store the data of your separator. For example, you should store the adjustable
2711  * parameters of the separator in this data structure. In a separator, user parameters for the maximal number of
2712  * separation rounds per node and for the maximal number of cuts separated per separation round might be useful.
2713  * If you are using C++, you can add separator data as usual as object variables to your class.
2714  * \n
2715  * Defining separator data is optional. You can leave the struct empty.
2716  *
2717  * @section SEPA_INTERFACE Interface Methods
2718  *
2719  * At the bottom of "sepa_myseparator.c", you can find the interface method SCIPincludeSepaMyseparator(),
2720  * which also appears in "sepa_myseparator.h"
2721  * SCIPincludeSepaMyseparator() is called by the user, if (s)he wants to include the separator,
2722  * i.e., if (s)he wants to use the separator in his/her application.
2723  *
2724  * This method only has to be adjusted slightly.
2725  * It is responsible for notifying SCIP of the presence of the separator. For this, you can either call SCIPincludeSepa(),
2726  * or SCIPincludeSepaBasic() since SCIP version 3.0. In the latter variant, \ref SEPA_ADDITIONALCALLBACKS "additional callbacks"
2727  * must be added via setter functions as, e.g., SCIPsetSepaCopy(). We recommend this latter variant because
2728  * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2729  * variant must be manually adjusted with every SCIP release containing new callbacks for separators in order to compile.
2730  *
2731  * If you are using separator data, you have to allocate the memory
2732  * for the data at this point. You can do this by calling:
2733  * \code
2734  * SCIP_CALL( SCIPallocMemory(scip, &sepadata) );
2735  * \endcode
2736  * You also have to initialize the fields in "struct SCIP_SepaData" afterwards. For freeing the
2737  * separator data, see \ref SEPAFREE.
2738  *
2739  * You may also add user parameters for your separator, see \ref PARAM for how to add user parameters and
2740  * the method SCIPincludeSepaGomory() in src/scip/sepa_gomory.c for an example.
2741  *
2742  *
2743  * @section SEPA_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Separator
2744  *
2745  * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
2746  * an operational algorithm.
2747  * They are passed together with the separator itself to SCIP using SCIPincludeSepa() or SCIPincludeSepaBasic(),
2748  * see @ref SEPA_INTERFACE.
2749  *
2750  * Separator plugins have two callbacks, @ref SEPAEXECLP and @ref SEPAEXECSOL, of which at least one must be implemented.
2751  *
2752  * Additional documentation for the callback methods, in particular to their input parameters,
2753  * can be found in type_sepa.h.
2754  *
2755  * @subsection SEPAEXECLP
2756  *
2757  * The SEPAEXECLP callback is executed during the price-and-cut loop of the subproblem processing.
2758  * It should try to generate general purpose cutting planes in order to separate the current LP solution.
2759  * The method is called in the LP solution loop, which means that a valid LP solution exists.
2760  *
2761  * Usually, the callback searches and produces cuts, that are added with a call to SCIPaddCut().
2762  * If the cut should be added to the global cut pool, it calls SCIPaddPoolCut().
2763  * In addition to LP rows, the callback may also produce domain reductions or add additional constraints.
2764  *
2765  * Overall, the SEPAEXECLP callback has the following options, which is indicated by the possible return values of
2766  * the 'result' variable (see type_sepa.h):
2767  * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
2768  * - adding an additional constraint (result SCIP_CONSADDED)
2769  * - reducing a variable's domain (result SCIP_REDUCEDDOM)
2770  * - adding a cutting plane to the LP (result SCIP_SEPARATED)
2771  * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
2772  * (result SCIP_DIDNOTFIND)
2773  * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
2774  * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
2775  * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
2776  *
2777  * @subsection SEPAEXECSOL
2778  *
2779  * The SEPAEXECSOL callback is executed during the separation loop on arbitrary primal solutions.
2780  * It should try to generate general purpose cutting planes in order to separate the given primal solution.
2781  * The method is not called in the LP solution loop, which means that there is no valid LP solution.
2782  *
2783  * In the standard SCIP environment, the SEPAEXECSOL callback is not used because only LP solutions are
2784  * separated. The SEPAEXECSOL callback provides means to support external relaxation handlers like semidefinite
2785  * relaxations that want to separate an intermediate primal solution vector. Thus, if you do not want to support
2786  * such external plugins, you do not need to implement this callback method.
2787  *
2788  * Usually, the callback searches and produces cuts, that are added with a call to SCIPaddCut().
2789  * If the cut should be added to the global cut pool, it calls SCIPaddPoolCut().
2790  * In addition to LP rows, the callback may also produce domain reductions or add other constraints.
2791  *
2792  * Overall, the SEPAEXECSOL callback has the following options, which is indicated by the possible return values of
2793  * the 'result' variable (see type_sepa.h):
2794  * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
2795  * - adding an additional constraint (result SCIP_CONSADDED)
2796  * - reducing a variable's domain (result SCIP_REDUCEDDOM)
2797  * - adding a cutting plane to the LP (result SCIP_SEPARATED)
2798  * - stating that the separator searched, but did not find domain reductions, cutting planes, or cut constraints
2799  * (result SCIP_DIDNOTFIND)
2800  * - stating that the separator was skipped (result SCIP_DIDNOTRUN)
2801  * - stating that the separator was skipped, but should be called again (result SCIP_DELAYED)
2802  * - stating that a new separation round should be started without calling the remaining separator methods (result SCIP_NEWROUND)
2803  *
2804  *
2805  * @section SEPA_ADDITIONALCALLBACKS Additional Callback Methods of a Separator
2806  *
2807  * The additional callback methods do not need to be implemented in every case. However, some of them have to be
2808  * implemented for most applications, they can be used, for example, to initialize and free private data.
2809  * Additional callbacks can either be passed directly with SCIPincludeSepa() to SCIP or via specific
2810  * <b>setter functions</b> after a call of SCIPincludeSepaBasic(), see also @ref SEPA_INTERFACE.
2811  *
2812  * @subsection SEPAFREE
2813  *
2814  * If you are using separator data (see \ref SEPA_DATA and \ref SEPA_INTERFACE), you have to implement this method
2815  * in order to free the separator data. This can be done by the following procedure:
2816  * \code
2817  * static
2818  * SCIP_DECL_SEPAFREE(sepaFreeMyseparator)
2819  * {
2820  * SCIP_SEPADATA* sepadata;
2821  *
2822  * sepadata = SCIPsepaGetData(sepa);
2823  * assert(sepadata != NULL);
2824  *
2825  * SCIPfreeMemory(scip, &sepadata);
2826  *
2827  * SCIPsepaSetData(sepa, NULL);
2828  *
2829  * return SCIP_OKAY;
2830  * }
2831  * \endcode
2832  * If you have allocated memory for fields in your separator data, remember to free this memory
2833  * before freeing the separator data itself.
2834  * If you are using the C++ wrapper class, this method is not available.
2835  * Instead, just use the destructor of your class to free the member variables of your class.
2836  *
2837  * @subsection SEPACOPY
2838  *
2839  * The SEPACOPY callback is executed when a SCIP instance is copied, e.g. to
2840  * solve a sub-SCIP. By
2841  * defining this callback as
2842  * <code>NULL</code> the user disables the execution of the specified
2843  * separator for all copied SCIP instances. This may deteriorate the performance
2844  * of primal heuristics using sub-SCIPs.
2845  *
2846  * @subsection SEPAINIT
2847  *
2848  * The SEPAINIT callback is executed after the problem is transformed.
2849  * The separator may, e.g., use this call to initialize its separator data.
2850  * The difference between the original and the transformed problem is explained in
2851  * "What is this thing with the original and the transformed problem about?" on \ref FAQ.
2852  *
2853  * @subsection SEPAEXIT
2854  *
2855  * The SEPAEXIT callback is executed before the transformed problem is freed.
2856  * In this method, the separator should free all resources that have been allocated for the solving process in SEPAINIT.
2857  *
2858  * @subsection SEPAINITSOL
2859  *
2860  * The SEPAINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
2861  * begin. The separator may use this call to initialize its branch-and-bound specific data.
2862  *
2863  * @subsection SEPAEXITSOL
2864  *
2865  * The SEPAEXITSOL callback is executed before the branch-and-bound process is freed. The separator should use this call
2866  * to clean up its branch-and-bound data, in particular to release all LP rows that it has created or captured.
2867  */
2868 
2869 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
2870 /**@page PROP How to add propagators
2871  *
2872  * Propagators are used to tighten the domains of the variables. Like for cutting planes, there are two different types
2873  * of domain propagations. Constraint based (primal) domain propagation algorithms are part of the corresponding
2874  * constraint handlers, see \ref CONSPROP. In contrast, domain propagators usually provide dual propagations, i.e.,
2875  * propagations that can be applied using the objective function and the current best known primal solution. This
2876  * section deals with such propagators.
2877  *
2878  * A complete list of all propagators contained in this release can be found \ref PROPAGATORS "here".
2879  *
2880  * We now explain how users can add their own propagators. Take the pseudo objective function propagator
2881  * (src/scip/prop_pseudoobj.c) as an example. As all other default plugins, it is written in C. C++ users can easily
2882  * adapt the code by using the scip::ObjProp wrapper base class and implement the @c scip_...() virtual methods instead
2883  * of the @c SCIP_DECL_PROP... callback methods.
2884  *
2885  * Additional documentation for the callback methods of a propagator can be found in the file type_prop.h.
2886  *
2887  * Here is what you have to do to implement a propagator:
2888  * -# Copy the template files src/scip/prop_xyz.c and src/scip/prop_xyz.h into files named "prop_mypropagator.c"
2889  * and "prop_mypropagator.h".
2890  * \n
2891  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
2892  * -# Use SCIPincludePropMypropagator() in order to include the propagator into your SCIP instance,
2893  * e.g., in the main file of your project (see, e.g., src/main.c in the Coloring example).
2894  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mypropagator".
2895  * -# Adjust the properties of the propagator (see \ref PROP_PROPERTIES).
2896  * -# Define the propagator data (see \ref PROP_DATA). This is optional.
2897  * -# Implement the interface methods (see \ref PROP_INTERFACE).
2898  * -# Implement the fundamental callback methods (see \ref PROP_FUNDAMENTALCALLBACKS).
2899  * -# Implement the additional callback methods (see \ref PROP_ADDITIONALCALLBACKS). This is optional.
2900  *
2901  * @section PROP_PROPERTIES Properties of a Propagator
2902  *
2903  * At the top of the new file "prop_mypropagator.c" you can find the propagator properties. These are given as compiler
2904  * defines. The presolving-related properties are optional,
2905  * they only have to be defined if the propagator supports presolving routines.
2906  * In the C++ wrapper class, you have to provide the propagator properties by calling the constructor of the
2907  * abstract base class scip::ObjProp from within your constructor. The properties you have the following meaning:
2908  *
2909  * @subsection PROP_FUNDAMENTALPROPERTIES Fundamental properties of a propagator
2910  *
2911  * \par PROP_NAME: the name of the propagator.
2912  * This name is used in the interactive shell to address the propagator. Additionally, if you are searching for a
2913  * propagator with SCIPfindProp(), this name is searched for. Names have to be unique: no two propagators may have the
2914  * same name.
2915  *
2916  * \par PROP_DESC: the description of the propagator.
2917  * This string is printed as a description of the propagator in the interactive shell.
2918  *
2919  * \par PROP_PRIORITY: the priority of the propagator.
2920  * In each propagation round, the propagators and propagation methods of the constraint handlers are called in a
2921  * predefined order, which is given by the priorities of the propagators and the check priorities of the constraint
2922  * handlers. First, the propagators with non-negative priority are called in order of decreasing priority. Next, the
2923  * propagation methods of the different constraint handlers are called in order of decreasing check priority. Finally,
2924  * the propagators with negative priority are called in order of decreasing priority. \n The priority of the
2925  * propagators should be set according to the complexity of the propagation algorithm and the impact of the domain
2926  * propagations: propagators providing fast algorithms that usually have a high impact (i.e., tighten many bounds)
2927  * should have a high priority.
2928  *
2929  * \par PROP_FREQ: the default frequency for propagating domains.
2930  * The frequency defines the depth levels at which the propagation method \ref PROPEXEC is called. For example, a
2931  * frequency of 7 means, that the propagation callback is executed for subproblems that are in depth 0, 7, 14, ... of
2932  * the branching tree. A frequency of 0 means that propagation is only applied in preprocessing and at the root node. A
2933  * frequency of -1 disables the propagator.
2934  * \n
2935  * The frequency can be adjusted by the user. This property of the propagator only defines the default value of the
2936  * frequency.\n
2937  * <b>Note:</b> If you want to have a more flexible control of when to execute the propagation algorithm, you have to
2938  * assign a frequency of 1 and implement a check at the beginning of your propagation algorithm whether you really want
2939  * to execute the domain propagation or not. If you do not want to execute it, set the result code to SCIP_DIDNOTRUN.
2940  *
2941  * \par PROP_DELAY: the default for whether the propagation method should be delayed, if other propagators or constraint handlers found domain reductions.
2942  * If the propagator's propagation method is marked to be delayed, it is only executed after no other propagator or
2943  * constraint handler found a domain reduction in the current iteration of the domain propagation loop. If the
2944  * propagation method of the propagator is very expensive, you may want to mark it to be delayed until all cheap
2945  * propagation methods have been executed.
2946  *
2947  * \par PROP_TIMING: the timing mask of the propagator.
2948  * SCIP calls the domain propagation routines at different places in the node processing loop.
2949  * This property indicates at which places the propagator is called.
2950  * Possible values are defined in type_timing.h and can be concatenated, e.g., as in SCIP_PROPTIMING_ALWAYS.
2951  *
2952  * @subsection PROP_ADDITIONALPROPERTIES Optional propagator properties
2953  *
2954  * The following properties are optional and only need to be defined if the propagator supports
2955  * presolving, that is, if the \ref PROPPRESOL "presolving callback" is implemented.
2956  *
2957  * \par PROP_PRESOL_PRIORITY: the priority of the presolving method.
2958  * This attribute is analogous to the PROP_PRIORITY flag, but deals with the preprocessing method of the presolver.
2959  *
2960  * \par PROP_PRESOL_MAXROUNDS: the default maximal number of presolving rounds the propagator participates in.
2961  * The preprocessing is executed in rounds.
2962  * If enough changes have been applied to the model, an additional preprocessing round is performed.
2963  * The MAXROUNDS parameter of a propagator denotes the maximal number of preprocessing rounds, the propagator
2964  * participates in.
2965  * A value of -1 means, that there is no limit on the number of rounds.
2966  * A value of 0 means, the preprocessing callback of the propagator is disabled.
2967  *
2968  * \par PROP_PRESOL_DELAY: the default for whether the presolving method should be delayed, if other propagators or constraint handlers found presolving reductions.
2969  * This property is analogous to the PROP_DELAY flag, but deals with the preprocessing method of the propagator.
2970  *
2971  * @section PROP_DATA Propagator Data
2972  *
2973  * Below the title "Data structures" you can find a struct called <code>struct SCIP_PropData</code>. In this data
2974  * structure, you can store the data of your propagator. For example, you should store the adjustable parameters of the
2975  * propagator in this data structure. If you are using C++, you can add propagator data as object variables to your
2976  * class as usual .
2977  * \n
2978  * Defining propagator data is optional. You can leave the struct empty.
2979  *
2980  *
2981  * @section PROP_INTERFACE Interface Methods
2982  *
2983  * At the bottom of "prop_mypropagator.c", you can find the interface method SCIPincludeSepaMypropagator(),
2984  * which also appears in "prop_mypropagator.h"
2985  * SCIPincludePropMypropagator() is called by the user, if (s)he wants to include the propagator,
2986  * i.e., if (s)he wants to use the propagator in his/her application.
2987  *
2988  * This method only has to be adjusted slightly.
2989  * It is responsible for notifying SCIP of the presence of the propagator. For this, you can either call SCIPincludeProp(),
2990  * or SCIPincludePropBasic() since SCIP version 3.0. In the latter variant, \ref PROP_ADDITIONALCALLBACKS "additional callbacks"
2991  * must be added via setter functions as, e.g., SCIPsetPropCopy(). We recommend this latter variant because
2992  * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
2993  * variant must be manually adjusted with every SCIP release containing new callbacks for separators in order to compile.
2994  *
2995  *
2996  * If you are using propagator data, you have to allocate the memory for the data at this point. You can do this by
2997  * calling
2998  * \code
2999  * SCIP_CALL( SCIPallocMemory(scip, &propdata) );
3000  * \endcode
3001  * You also have to initialize the fields in <code>struct SCIP_PropData</code> afterwards.
3002  *
3003  * You may also add user parameters for your propagator, see the method SCIPincludePropPseudoobj() in
3004  * src/scip/prop_pseudoobj.c for an example.
3005  *
3006  *
3007  * @section PROP_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Propagator
3008  *
3009  * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
3010  * an operational algorithm.
3011  * They are passed together with the propagator itself to SCIP using SCIPincludeProp() or SCIPincludePropBasic(),
3012  * see @ref PROP_INTERFACE.
3013  *
3014  * Propagator plugins have one fundamental callback method, namely the \ref PROPEXEC method
3015  * method. This method has to be implemented for every propagator; the other callback methods are optional. In the
3016  * C++ wrapper class scip::ObjProp, the scip_exec() method (which corresponds to the \ref PROPEXEC
3017  * callback) is a virtual abstract member function. You have to
3018  * implement it in order to be able to construct an object of your propagator class.
3019  *
3020  * Additional documentation for the callback methods can be found in type_prop.h.
3021  *
3022  * @subsection PROPEXEC
3023  *
3024  * The PROPEXEC callback is called during presolving and during the subproblem processing. It should perform the actual
3025  * domain propagation, which means that it should tighten the variables' bounds. The technique of domain propagation,
3026  * which is the main workhorse of constraint programming, is called "node preprocessing" in the Integer Programming
3027  * community.
3028  *
3029  * The PROPEXEC callback has the following options:
3030  * - detecting that the node is infeasible in the variables' bounds and can be cut off (result SCIP_CUTOFF)
3031  * - reducing (i.e, tightening) the domains of some variables (result SCIP_REDUCEDDOM)
3032  * - stating that the propagator searched, but did not find domain reductions, cutting planes, or cut constraints
3033  * (result SCIP_DIDNOTFIND)
3034  * - stating that the propagator was skipped (result SCIP_DIDNOTRUN)
3035  * - stating that the propagator was skipped, but should be called again (result SCIP_DELAYED)
3036  *
3037  *
3038  *
3039  * @section PROP_ADDITIONALCALLBACKS Additional Callback Methods of a Propagator
3040  *
3041  * The additional callback methods do not need to be implemented in every case. However, some of them have to be
3042  * implemented for most applications, they can be used, for example, to initialize and free private data.
3043  * Additional callbacks can either be passed directly with SCIPincludeProp() to SCIP or via specific
3044  * <b>setter functions</b> after a call of SCIPincludePropBasic(), see also @ref PROP_INTERFACE.
3045  *
3046  * @subsection PROPRESPROP
3047  *
3048  * If the propagator wants to support \ref CONF "conflict analysis", it has to supply the PROPRESPROP method. It also should call
3049  * SCIPinferVarLbProp() or SCIPinferVarUbProp() in the domain propagation instead of SCIPchgVarLb() or SCIPchgVarUb() in
3050  * order to deduce bound changes on variables. In the SCIPinferVarLbProp() and SCIPinferVarUbProp() calls, the
3051  * propagator provides a pointer to itself and an integer value "inferinfo" that can be arbitrarily chosen.
3052  *
3053  * The propagation conflict resolving method PROPRESPROP must then be implemented to provide the "reasons" for the bound
3054  * changes, i.e., the bounds of variables at the time of the propagation, which forced the propagator to set the
3055  * conflict variable's bound to its current value. It can use the "inferinfo" tag to identify its own propagation rule
3056  * and thus identify the "reason" bounds. The bounds that form the reason of the assignment must then be provided by
3057  * calls to SCIPaddConflictLb() and SCIPaddConflictUb() in the propagation conflict resolving method.
3058  *
3059  * See the description of the propagation conflict resolving method \ref CONSRESPROP of constraint handlers for
3060  * further details.
3061  *
3062  * Omitting the PROPRESPROP callback circumvents the implementation of the usually rather complex conflict resolving method.
3063  * Yet, it
3064  * will make the conflict analysis less effective. We suggest to first omit the conflict resolving method and check how
3065  * effective the propagation method is. If it produces a lot of propagations for your application, you definitely should
3066  * consider implementing the conflict resolving method.
3067  *
3068  *
3069  * @subsection PROPFREE
3070  *
3071  * If you are using propagator data, you have to implement this method in order to free the propagator data.
3072  * This can be done by the following procedure:
3073  * \code
3074  * static
3075  * SCIP_DECL_PROPFREE(propFreeMypropagator)
3076  * {
3077  * SCIP_PROPDATA* propdata;
3078  *
3079  * propdata = SCIPpropGetData(prop);
3080  * assert(propdata != NULL);
3081  *
3082  * SCIPfreeMemory(scip, &propdata);
3083  *
3084  * SCIPpropSetData(prop, NULL);
3085  *
3086  * return SCIP_OKAY;
3087  * }
3088  * \endcode
3089  * If you have allocated memory for fields in your propagator data, remember to free this memory
3090  * before freeing the propagator data itself.
3091  * If you are using the C++ wrapper class, this method is not available.
3092  * Instead, just use the destructor of your class to free the member variables of your class.
3093  *
3094  * @subsection PROPINIT
3095  *
3096  * The PROPINIT callback is executed after the problem is transformed. The propagator may, e.g., use this call to
3097  * initialize its propagator data.
3098  *
3099  * @subsection PROPCOPY
3100  *
3101  * The PROPCOPY callback is executed when a SCIP instance is copied, e.g. to
3102  * solve a sub-SCIP. By
3103  * defining this callback as
3104  * <code>NULL</code> the user disables the execution of the specified
3105  * propagator for all copied SCIP instances. This may deteriorate the performance
3106  * of primal heuristics using sub-SCIPs.
3107  *
3108  * @subsection PROPEXIT
3109  *
3110  * The PROPEXIT callback is executed before the transformed problem is freed.
3111  * In this method, the propagator should free all resources that have been allocated for the solving process in PROPINIT.
3112  *
3113  * @subsection PROPINITPRE
3114  *
3115  * The PROPINITPRE callback is executed before the preprocessing is started, even if presolving is turned off.
3116  * The propagator may use this call to initialize its presolving data before the presolving process begins.
3117  *
3118  * @subsection PROPEXITPRE
3119  *
3120  * The PROPEXITPRE callback is executed after the preprocessing has been finished, even if presolving is turned off.
3121  * The propagator may use this call, e.g., to clean up its presolving data.
3122  * Besides clean up, no time consuming operations should be done.
3123  *
3124  * @subsection PROPINITSOL
3125  *
3126  * The PROPINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3127  * begin.
3128  * The propagator may use this call to initialize its branch-and-bound specific data.
3129  *
3130  * @subsection PROPEXITSOL
3131  *
3132  * The PROPEXITSOL callback is executed before the branch-and-bound process is freed.
3133  * The propagator should use this call to clean up its branch-and-bound data.
3134  *
3135  * @subsection PROPPRESOL
3136  *
3137  * Seaches for domain propagations, analogous to the \ref PROPEXEC callback.
3138  * However, this callback is called during preprocessing.
3139  *
3140  * To inform SCIP that the presolving method found a reduction the result pointer has to be set in a proper way.
3141  * The following options are possible:
3142  *
3143  * - SCIP_UNBOUNDED : at least one variable is not bounded by any constraint in objective direction
3144  * - SCIP_CUTOFF : at least one domain reduction that renders the problem infeasible has been found
3145  * - SCIP_SUCCESS : the presolver found a domain reduction
3146  * - SCIP_DIDNOTFIND : the presolver searched, but did not find a presolving change
3147  * - SCIP_DIDNOTRUN : the presolver was skipped
3148  * - SCIP_DELAYED : the presolver was skipped, but should be called again
3149  *
3150  *
3151  * Please see also the @ref PROP_ADDITIONALPROPERTIES section to learn about the properties
3152  * PROP_PRESOL_PRIORITY, PROP_PRESOL_MAXROUNDS, and PROP_PRESOL_DELAY, which influence the behaviour of SCIP
3153  * calling PROPPRESOL.
3154  *
3155  */
3156 
3157 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3158 /**@page BRANCH How to add branching rules
3159  *
3160  * Branching rules are used to split the problem at the current node into smaller subproblems. Branching rules can be called at three
3161  * different occasions, which is why they have three different execution methods (see \ref
3162  * BRANCHRULE_ADDITIONALCALLBACKS). Branching is performed if:
3163  * - the LP solution of the current problem is fractional. In this case, the integrality constraint handler calls the
3164  * \ref BRANCHEXECLP methods of the branching rules.
3165  * - the list of external branching candidates is not empty. This will only be the case if branching candidates were added
3166  * by a user's \ref RELAX "relaxation handler" or \ref CONS "constraint handler" plugin, calling SCIPaddExternBranchCand().
3167  * These branching candidates should be processed by the \ref BRANCHEXECEXT method.
3168  * - if an integral solution violates one or more constraints and this infeasibility could not be resolved in the callback methods
3169  * \ref CONSENFOLP and \ref CONSENFOPS of the corresponding constraint handlers. In this case, the \ref BRANCHEXECPS method will be called. This is the
3170  * 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
3171  * branching on pseudo solutions works as a last resort.
3172  *
3173  * The idea of branching rules is to take a global view on the problem. In contrast, branching paradigms which are
3174  * specific to one type of constraint are best implemented within the enforcement callbacks of your constraint handler.
3175  * See, e.g., the constraint specific branching rules provided by the constraint handlers for special ordered sets
3176  * (src/scip/cons_sos{1,2}.c)).
3177  * \n
3178  * All branching rules that come with the default distribution of SCIP create two subproblems by splitting a single
3179  * variable's domain. It is, however, fully supported to implement much more general branching schemes, for example by
3180  * creating more than two subproblems, or by adding additional constraints to the subproblems instead of tightening the
3181  * domains of the variables.
3182  * \n
3183  * A complete list of all branching rules contained in this release can be found \ref BRANCHINGRULES "here".
3184  *
3185  * We now explain how users can add their own branching rules. Take the most infeasible LP branching rule
3186  * (src/scip/branch_mostinf.c) as an example. As all other default plugins, it is written in C. C++ users can easily
3187  * adapt the code by using the scip::ObjBranchrule wrapper base class and implement the scip_...() virtual methods instead of
3188  * the SCIP_DECL_BRANCH... callback methods.
3189  *
3190  * Additional documentation for the callback methods of a branching rule can be found in the file type_branch.h.
3191  *
3192  * Here is what you have to do to implement a branching rule:
3193  * -# Copy the template files src/scip/branch_xyz.c and src/scip/branch_xyz.h into files named
3194  * "branch_mybranchingrule.c" and "branch_mybranchingrule.h".
3195  * \n
3196  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
3197  * -# Use SCIPincludeBranchruleMybranchingrule() in order to include the branching rule into your SCIP instance,
3198  * e.g., in the main file of your project (see, e.g., src/main.c in the Coloring example).
3199  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mybranchingrule".
3200  * -# Adjust the properties of the branching rule (see \ref BRANCHRULE_PROPERTIES).
3201  * -# Define the branching rule data (see \ref BRANCHRULE_DATA). This is optional.
3202  * -# Implement the interface methods (see \ref BRANCHRULE_INTERFACE).
3203  * -# Implement the fundamental callback methods (see \ref BRANCHRULE_FUNDAMENTALCALLBACKS).
3204  * -# Implement the additional callback methods (see \ref BRANCHRULE_ADDITIONALCALLBACKS). This is optional.
3205  *
3206  *
3207  * @section BRANCHRULE_PROPERTIES Properties of a Branching Rule
3208  *
3209  * At the top of the new file "branch_mybranchingrule.c" you can find the branching rule properties.
3210  * These are given as compiler defines.
3211  * In the C++ wrapper class, you have to provide the branching rule properties by calling the constructor
3212  * of the abstract base class scip::ObjBranchrule from within your constructor.
3213  * The properties you have to set have the following meaning:
3214  *
3215  * \par BRANCHRULE_NAME: the name of the branching rule.
3216  * This name is used in the interactive shell to address the branching rule.
3217  * Additionally, if you are searching for a branching rule with SCIPfindBranchrule(), this name is looked up.
3218  * Names have to be unique: no two branching rules may have the same name.
3219  *
3220  * \par BRANCHRULE_DESC: the description of the branching rule.
3221  * This string is printed as a description of the branching rule in the interactive shell.
3222  *
3223  * \par BRANCHRULE_PRIORITY: the default value for the priority of the branching rule.
3224  * In the subproblem processing, the branching rules are called in decreasing order of their priority until
3225  * one succeeded to branch. Since most branching rules are able to generate a branching in all situations,
3226  * only the rule of highest priority is used. In combination with the BRANCHRULE_MAXDEPTH and
3227  * BRANCHRULE_MAXBOUNDDIST settings, however, interesting strategies can be easily employed. For example,
3228  * the user can set the priority of the "full strong branching" strategy to the highest value and assign the
3229  * second highest value to the "reliable pseudo cost" rule. If (s)he also sets the maximal depth for the
3230  * "full strong branching" to 5, in the top 5 depth levels of the search tree the "full strong branching" is
3231  * applied, while in the deeper levels "reliable pseudo cost branching" is used.
3232  * \n
3233  * Note that the BRANCHRULE_PRIORITY property only specifies the default value of the priority. The user can
3234  * change this value arbitrarily.
3235  *
3236  * \par BRANCHRULE_MAXDEPTH: the default value for the maximal depth level of the branching rule.
3237  * This parameter denotes the maximal depth level in the branch-and-bound tree up to which the branching method of the
3238  * branching rule will be applied. Use -1 for no limit.
3239  * \n
3240  * Note that this property only specifies the default value. The user can change this value arbitrarily.
3241  *
3242  * \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.
3243  * At the current branch-and-bound node, the relative distance from its dual bound (local dual bound)
3244  * to the primal bound compared to the best node's dual bound (global dual bound) is considered. The branching method of
3245  * the branching rule will only be applied at the node if this relative distance does not exceed BRANCHRULE_MAXBOUNDDIST.
3246  * \n
3247  * For example, if the global dual bound is 50 and the primal bound is 60, BRANCHRULE_MAXBOUNDDIST = 0.25 means that
3248  * 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
3249  * 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
3250  * current best node only or at all nodes, respectively.
3251  * \n
3252  * Note that the BRANCHRULE_MAXBOUNDDIST property only specifies the default value of the maximal bound distance.
3253  * The user can change this value arbitrarily.
3254  *
3255  *
3256  * @section BRANCHRULE_DATA Branching Rule Data
3257  *
3258  * Below the header "Data structures" you can find a struct which is called "struct SCIP_BranchruleData".
3259  * In this data structure, you can store the data of your branching rule. For example, you should store the adjustable
3260  * parameters of the branching rule in this data structure.
3261  * If you are using C++, you can add branching rule data as usual as object variables to your class.
3262  * \n
3263  * Defining branching rule data is optional. You can leave the struct empty.
3264  *
3265  *
3266  * @section BRANCHRULE_INTERFACE Interface Methods
3267  *
3268  * At the bottom of "branch_mybranchingrule.c", you can find the interface method SCIPincludeBranchruleMybranchingrule(),
3269  * which also appears in "branch_mybranchingrule.h"
3270  * SCIPincludeBranchruleMybranchingrule() is called by the user, if (s)he wants to include the branching rule,
3271  * i.e., if (s)he wants to use the branching rule in his/her application.
3272  *
3273  * This method only has to be adjusted slightly.
3274  * It is responsible for notifying SCIP of the presence of the branching rule. For this, you can either call
3275  * SCIPincludeBranchrule(),
3276  * or SCIPincludeBranchruleBasic() since SCIP version 3.0. In the latter variant, \ref BRANCHRULE_ADDITIONALCALLBACKS "additional callbacks"
3277  * must be added via setter functions as, e.g., SCIPsetBranchruleCopy(). We recommend this latter variant because
3278  * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3279  * variant must be manually adjusted with every SCIP release containing new callbacks for branchrule in order to compile.
3280  *
3281  *
3282  * If you are using branching rule data, you have to allocate the memory for the data at this point.
3283  * You can do this by calling:
3284  * \code
3285  * SCIP_CALL( SCIPallocMemory(scip, &branchruledata) );
3286  * \endcode
3287  * You also have to initialize the fields in struct SCIP_BranchruleData afterwards.
3288  *
3289  * You may also add user parameters for your branching rule, see the method SCIPincludeBranchruleRelpscost() in
3290  * src/scip/branch_relpscost.c for an example.
3291  *
3292  *
3293  * @section BRANCHRULE_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Branching Rule
3294  *
3295  * Branching rules do not have any fundamental callback methods, i.e., all callback methods are optional.
3296  * In most cases, however, you want to implement the \ref BRANCHEXECLP method and sometimes the \ref BRANCHEXECPS method.
3297  *
3298  *
3299  * @section BRANCHRULE_ADDITIONALCALLBACKS Additional Callback Methods of a Branching Rule
3300  *
3301  * The additional callback methods do not need to be implemented in every case. However, some of them have to be
3302  * implemented for most applications, they can be used, for example, to initialize and free private data.
3303  * Additional callbacks can either be passed directly with SCIPincludeBranchrule() to SCIP or via specific
3304  * <b>setter functions</b> after a call of SCIPincludeBranchruleBasic(), see also @ref BRANCHRULE_INTERFACE.
3305  *
3306  * The most important callback methods are the \ref BRANCHEXECLP, \ref BRANCHEXECEXT,
3307  * and \ref BRANCHEXECPS methods, which perform the actual task of generating a branching.
3308  *
3309  * Additional documentation for the callback methods can be found in type_branch.h.
3310  *
3311  * @subsection BRANCHEXECLP
3312  *
3313  * The BRANCHEXECLP callback is executed during node processing if a fractional LP solution is available. It should
3314  * split the current problem into smaller subproblems. Usually, the branching is done in a way such that the current
3315  * fractional LP solution is no longer feasible in the relaxation of the subproblems. It is, however, possible to
3316  * create a child node for which the fractional LP solution is still feasible in the relaxation, for example, by
3317  * branching on a variable with integral LP value. In every case, you have to make sure that each subproblem is a
3318  * proper restriction of the current problem. Otherwise, you risk to produce an infinite path in the search tree.
3319  *
3320  * The user gains access to the branching candidates, i.e., to the fractional variables, and their LP solution values by
3321  * calling the method SCIPgetLPBranchCands(). Furthermore, SCIP provides two methods for performing the actual
3322  * branching, namely SCIPbranchVar() and SCIPcreateChild().
3323  *
3324  * Given an integral variable \f$x\f$ with fractional LP solution value \f$x^*\f$, the method SCIPbranchVar() creates
3325  * two child nodes; one contains the bound \f$x \le \lfloor x^* \rfloor\f$ and the other one contains the bound \f$x \ge
3326  * \lceil x^* \rceil\f$, see the BRANCHEXECLP callback in src/scip/branch_mostinf.c for an example. In addition, if a
3327  * proven lower objective bound of a created child node is known, like after strong branching has been applied, the user
3328  * may call the method SCIPupdateNodeLowerbound() in order to update the child node's lower bound.
3329  *
3330  * Please also see the \ref BRANCHEXEC "further information for the three execution methods".
3331  *
3332  * @subsection BRANCHEXECEXT
3333  *
3334  * The BRANCHEXECEXT callback is executed during node processing if no LP solution is available and the list of
3335  * external branching candidates is not empty. It should split the current problem into smaller subproblems. If you
3336  * do not use relaxation handlers or constraints handlers that provide external branching candidates, you do not need to
3337  * implement this callback.
3338  *
3339  * In contrast to the LP branching candidates and the pseudo branching candidates, the list of external branching
3340  * candidates will not be generated automatically. The user has to add all variables to the list by calling
3341  * SCIPaddExternBranchCand() for each of them. Usually, this will happen in the execution method of a relaxation handler or in the
3342  * enforcement methods of a constraint handler.
3343  *
3344  * The user gains access to these branching candidates by calling the method SCIPgetExternBranchCands(). Furthermore,
3345  * SCIP provides two methods for performing the actual branching with a given solution value, namely SCIPbranchVarVal()
3346  * and SCIPcreateChild(). SCIPbranchVarVal() allows users to specify the branching point for a variable in contrast to
3347  * SCIPbranchVar(), which will always use the current LP or pseudo solution.
3348  *
3349  * This paragraph contains additional information regarding how the method SCIPbranchVarVal() works. For external branching candidates,
3350  * there are three principle possibilities:
3351  * - Given a continuous variable \f$x\f$ with solution value \f$x^*\f$, the method SCIPbranchVarVal() creates
3352  * two child nodes; one contains the bound \f$x \le x^* \f$ and the other one contains the bound \f$x \ge x^* \f$.
3353  * - Given an integer variable \f$x\f$ with fractional solution value \f$x^*\f$, the method
3354  * SCIPbranchVarVal() creates two child nodes; one contains the bound \f$x \le \lfloor x^* \rfloor\f$ and the other
3355  * one contains the bound \f$x \ge \lceil x^* \rceil\f$.
3356  * - Given an integer variable \f$x\f$ with integral solution value \f$x^*\f$, the method SCIPbranchVarVal()
3357  * creates three child nodes; one contains the bound \f$x \le x^* -1\f$, one contains the bound \f$x \ge x^* +1\f$,
3358  * one contains the fixing \f$x = x^*\f$.
3359  *
3360  * See the BRANCHEXECEXT callback in src/scip/branch_random.c for an example. In addition, if a proven lower bound of a
3361  * created child node is known the user may call the method SCIPupdateNodeLowerbound() in order to update the child
3362  * node's lower bound.
3363  *
3364  * Please also see the \ref BRANCHEXEC "further information for the three execution methods".
3365  *
3366  * @subsection BRANCHEXECPS
3367  *
3368  * The BRANCHEXECPS callback is executed during node processing if no LP solution is available and at least one of the
3369  * integer variables is not yet fixed. It should split the current problem into smaller subproblems. PS stands for
3370  * pseudo solution which is the vector of all variables set to their locally best (w.r.t. the objective function)
3371  * bounds.
3372  *
3373  * The user gains access to the branching candidates, i.e., to the non-fixed integer variables, by calling the method
3374  * SCIPgetPseudoBranchCands(). Furthermore, SCIP provides two methods for performing the actual branching, namely
3375  * SCIPbranchVar() and SCIPcreateChild().
3376  *
3377  * Given an integer variable \f$x\f$ with bounds \f$[l,u]\f$ and not having solved the LP, the method SCIPbranchVar()
3378  * creates two child nodes:
3379  * - If both bounds are finite, then the two children will contain the domain reductions \f$x \le x^*\f$, and \f$x \ge
3380  * x^*+1\f$ with \f$x^* = \lfloor \frac{l + u}{2}\rfloor\f$. The current pseudo solution will remain feasible in one
3381  * of the branches, but the hope is that halving the domain's size leads to good propagations.
3382  * - If only one of the bounds is finite, the variable will be fixed to that bound in one of the child nodes. In the
3383  * other child node, the bound will be shifted by one.
3384  * - If both bounds are infinite, three children will be created: \f$x \le 1\f$, \f$x \ge 1\f$, and \f$x = 0\f$.
3385 
3386  *
3387  * See the BRANCHEXECPS callback in src/scip/branch_random.c for an example. In addition, if a proven lower bound of a
3388  * created child node is known, the user may call the method SCIPupdateNodeLowerbound() in order to update the child
3389  * node's lower bound.
3390  *
3391  * Please also see the \ref BRANCHEXEC "further information for the three execution methods".
3392  *
3393  * @subsection BRANCHEXEC Further information for the three execution methods
3394  *
3395  * In order to apply more general branching schemes, one should use the method SCIPcreateChild().
3396  * After having created a child node, the additional restrictions of the child node have to be added with calls to
3397  * SCIPaddConsNode(), SCIPchgVarLbNode(), or SCIPchgVarUbNode().
3398  * \n
3399  * In the method SCIPcreateChild(), the branching rule has to assign two values to the new nodes: a node selection
3400  * priority for each node and an estimate for the objective value of the best feasible solution contained in the subtree
3401  * after applying the branching. If the method SCIPbranchVar() is used, these values are automatically assigned. For
3402  * variable based branching schemes, one might use the methods SCIPcalcNodeselPriority() and the method
3403  * SCIPcalcChildEstimate().
3404  *
3405  * In some cases, the branching rule can tighten the current subproblem instead of producing a branching. For example,
3406  * strong branching might have proven that rounding up a variable would lead to an infeasible LP relaxation and thus,
3407  * the variable must be rounded down. Therefore, the BRANCHEXECLP, BRANCHEXECPS and BRANCHEXECREL callbacks may also
3408  * produce domain reductions or add additional constraints to the current subproblem.
3409  *
3410  * The execution callbacks have the following options:
3411  * - detecting that the node is infeasible and can be cut off (result SCIP_CUTOFF)
3412  * - adding an additional constraint (e.g. a conflict constraint) (result SCIP_CONSADDED; note that this action
3413  * must not be performed if the input "allowaddcons" is FALSE)
3414  * - reducing the domain of a variable such that the current LP solution becomes infeasible (result SCIP_REDUCEDDOM)
3415  * - applying a branching (result SCIP_BRANCHED)
3416  * - stating that the branching rule was skipped (result SCIP_DIDNOTRUN).
3417  *
3418  * Only the BRANCHEXECLP callback has the possibility to add a cutting plane to the LP (result SCIP_SEPARATED).
3419  *
3420  * @subsection BRANCHFREE
3421  *
3422  * If you are using branching rule data, you have to implement this method in order to free the branching rule data.
3423  * This can be done by the following procedure:
3424  * \code
3425  * static
3426  * SCIP_DECL_BRANCHFREE(branchFreeMybranchingrule)
3427  * {
3428  * SCIP_BRANCHRULEDATA* branchruledata;
3429  *
3430  * branchruledata = SCIPbranchruleGetData(branchrule);
3431  * assert(branchruledata != NULL);
3432  *
3433  * SCIPfreeMemory(scip, &branchruledata);
3434  *
3435  * SCIPbranchruleSetData(branchrule, NULL);
3436  *
3437  * return SCIP_OKAY;
3438  * }
3439  * \endcode
3440  * If you have allocated memory for fields in your branching rule data, remember to free this memory
3441  * before freeing the branching rule data itself.
3442  * If you are using the C++ wrapper class, this method is not available.
3443  * Instead, just use the destructor of your class to free the member variables of your class.
3444  *
3445  * @subsection BRANCHINIT
3446  *
3447  * The BRANCHINIT callback is executed after the problem is transformed.
3448  * The branching rule may, e.g., use this call to initialize its branching rule data.
3449  *
3450  * @subsection BRANCHCOPY
3451  *
3452  * The BRANCHCOPY callback is executed when a SCIP instance is copied, e.g. to
3453  * solve a sub-SCIP. By
3454  * defining this callback as
3455  * <code>NULL</code> the user disables the execution of the specified
3456  * branching rule for all copied SCIP instances. This may deteriorate the performance
3457  * of primal heuristics using sub-SCIPs.
3458  *
3459  * @subsection BRANCHEXIT
3460  *
3461  * The BRANCHEXIT callback is executed before the transformed problem is freed.
3462  * In this method, the branching rule should free all resources that have been allocated for the solving process in
3463  * BRANCHINIT.
3464  *
3465  * @subsection BRANCHINITSOL
3466  *
3467  * The BRANCHINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3468  * begin.
3469  * The branching rule may use this call to initialize its branch-and-bound specific data.
3470  *
3471  * @subsection BRANCHEXITSOL
3472  *
3473  * The BRANCHEXITSOL callback is executed before the branch-and-bound process is freed.
3474  * The branching rule should use this call to clean up its branch-and-bound data.
3475  */
3476 
3477 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3478 /**@page NODESEL How to add node selectors
3479  *
3480  * Node selectors are used to decide which of the leaves in the current branching tree is selected as next subproblem
3481  * to be processed. The ordering relation of the tree's leaves for storing them in the leaf priority queue is also
3482  * defined by the node selectors.
3483  * \n
3484  * A complete list of all node selectors contained in this release can be found \ref NODESELECTORS "here".
3485  *
3486  * We now explain how users can add their own node selectors.
3487  * Take the node selector for depth first search (src/scip/nodesel_dfs.c) as an example.
3488  * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjNodesel wrapper
3489  * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_NODESEL... callback methods.
3490  *
3491  * Additional documentation for the callback methods of a node selector can be found in the file type_nodesel.h.
3492  *
3493  * Here is what you have to do to implement a node selector:
3494  * -# Copy the template files src/scip/nodesel_xyz.c and src/scip/nodesel_xyz.h into files named "nodesel_mynodeselector.c"
3495  * and "nodesel_mynodeselector.h".
3496  * \n
3497  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
3498  * -# Use SCIPincludeNodeselMynodeselector() in oder to include the node selector into your SCIP instance,
3499  * e.g., in the main file of your project (see, e.g., src/main.c in the Coloring example).
3500  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mynodeselector".
3501  * -# Adjust the properties of the node selector (see \ref NODESEL_PROPERTIES).
3502  * -# Define the node selector data (see \ref NODESEL_DATA). This is optional.
3503  * -# Implement the interface methods (see \ref NODESEL_INTERFACE).
3504  * -# Implement the fundamental callback methods (see \ref NODESEL_FUNDAMENTALCALLBACKS).
3505  * -# Implement the additional callback methods (see \ref NODESEL_ADDITIONALCALLBACKS). This is optional.
3506  *
3507  *
3508  * @section NODESEL_PROPERTIES Properties of a Node Selector
3509  *
3510  * At the top of the new file "nodesel_mynodeselector.c" you can find the node selector properties.
3511  * These are given as compiler defines.
3512  * In the C++ wrapper class, you have to provide the node selector properties by calling the constructor
3513  * of the abstract base class scip::ObjNodesel from within your constructor.
3514  * The properties you have to set have the following meaning:
3515  *
3516  * \par NODESEL_NAME: the name of the node selector.
3517  * This name is used in the interactive shell to address the node selector.
3518  * Additionally, if you are searching for a node selector with SCIPfindNodesel(), this name is looked up.
3519  * Names have to be unique: no two node selectors may have the same name.
3520  *
3521  * \par NODESEL_DESC: the description of the node selector.
3522  * This string is printed as a description of the node selector in the interactive shell.
3523  *
3524  * \par NODESEL_STDPRIORITY: the default priority of the node selector in the standard mode.
3525  * The first step of each iteration of the main solving loop is the selection of the next subproblem to be processed.
3526  * The node selector of highest priority (the active node selector) is called to do this selection.
3527  * In particular, if you implemented your own node selector plugin which you want to be applied, you should choose a priority
3528  * which is greater then all priorities of the SCIP default node selectors.
3529  * Note that SCIP has two different operation modes: the standard mode and the memory saving mode. If the memory
3530  * limit - given as a parameter by the user - is almost reached, SCIP switches from the standard mode to the memory saving
3531  * mode in which different priorities for the node selectors are applied. NODESEL_STDPRIORITY is the priority of the
3532  * node selector used in the standard mode.
3533  * \n
3534  * Note that this property only defines the default value of the priority. The user may change this value arbitrarily by
3535  * adjusting the corresponding parameter setting.
3536  *
3537  * \par NODESEL_MEMSAVEPRIORITY: the default priority of the node selector in the memory saving mode.
3538  * The priority NODESEL_MEMSAVEPRIORITY of the node selector has the same meaning as the priority NODESEL_STDPRIORITY, but
3539  * is used in the memory saving mode.
3540  * Usually, you want the best performing node selector, for example best estimate search, to have maximal
3541  * standard priority, while you want a node selector which tends to keep the growth of the search tree limited, for example
3542  * depth first search, to have maximal memory saving priority.
3543  * \n
3544  * Note that this property only defines the default value of the priority. The user may change this value arbitrarily by
3545  * adjusting the corresponding parameter setting.
3546  *
3547  *
3548  * @section NODESEL_DATA Node Selector Data
3549  *
3550  * Below the header "Data structures" you can find a struct which is called "struct SCIP_NodeselData".
3551  * In this data structure, you can store the data of your node selector. For example, you should store the adjustable
3552  * parameters of the node selector in this data structure.
3553  * If you are using C++, you can add node selector data as usual as object variables to your class.
3554  * \n
3555  * Defining node selector data is optional. You can leave the struct empty.
3556  *
3557  *
3558  * @section NODESEL_INTERFACE Interface Methods
3559  *
3560  * At the bottom of "nodesel_mynodeselector.c", you can find the interface method SCIPincludeNodeselMynodeselector(),
3561  * which also appears in "nodesel_mynodeselector.h"
3562  * SCIPincludeNodeselMynodeselector() is called by the user, if (s)he wants to include the node selector,
3563  * i.e., if (s)he wants to use the node selector in his/her application.
3564  *
3565  * This method only has to be adjusted slightly.
3566  * It is responsible for notifying SCIP of the presence of the node selector. For this, you can either call
3567  * SCIPincludeNodesel(),
3568  * or SCIPincludeNodeselBasic() since SCIP version 3.0. In the latter variant, \ref NODESEL_ADDITIONALCALLBACKS "additional callbacks"
3569  * must be added via setter functions as, e.g., SCIPsetNodeselCopy(). We recommend this latter variant because
3570  * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3571  * variant must be manually adjusted with every SCIP release containing new callbacks for node selectors in order to compile.
3572  *
3573  *
3574  * If you are using node selector data, you have to allocate the memory for the data at this point.
3575  * You can do this by calling:
3576  * \code
3577  * SCIP_CALL( SCIPallocMemory(scip, &nodeseldata) );
3578  * \endcode
3579  * You also have to initialize the fields in struct SCIP_NodeselData afterwards.
3580  *
3581  * You may also add user parameters for your node selector, see the method SCIPincludeNodeselRestartdfs() in
3582  * src/scip/nodesel_restartdfs.c for an example.
3583  *
3584  *
3585  * @section NODESEL_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Node Selector
3586  *
3587  * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
3588  * an operational algorithm.
3589  * They are passed together with the node selector itself to SCIP using SCIPincludeNodesel() or SCIPincludeNodeselBasic(),
3590  * see @ref NODESEL_INTERFACE.
3591  *
3592  * Node selector plugins have two fundamental callback methods, namely the NODESELSELECT method and the NODESELCOMP method.
3593  * These methods have to be implemented for every node selector; the other callback methods are optional.
3594  * They implement the two requirements every node selector has to fulfill: Selecting a node from the queue to be processed
3595  * next and, given two nodes, deciding which of both is favored by the node selector's selection rule. The first
3596  * task is implemented in the NODESELSELECT callback, the second one in the NODESELCOMP callback.
3597  * In the C++ wrapper class scip::ObjNodesel, the scip_select() method and the scip_comp() method (which correspond to the
3598  * NODESELSELECT callback and the NODESELCOMP callback, respectively) are virtual abstract member functions.
3599  * You have to implement them in order to be able to construct an object of your node selector class.
3600  *
3601  * Additional documentation for the callback methods can be found in type_nodesel.h.
3602  *
3603  * @subsection NODESELSELECT
3604  *
3605  * The NODESELSELECT callback is the first method called in each iteration in the main solving loop. It should decide
3606  * which of the leaves in the current branching tree is selected as the next subproblem to be processed.
3607  * It can arbitrarily decide between all leaves stored in the tree, but for performance reasons,
3608  * the current node's children and siblings are often treated different from the remaining leaves.
3609  * This is mainly due to the warm start capabilities of the simplex algorithm and the expectation that the bases of
3610  * neighboring vertices in the branching tree very similar.
3611  * The node selector's choice of the next node to process can
3612  * have a large impact on the solver's performance, because it influences the finding of feasible solutions and the
3613  * development of the global dual bound.
3614  *
3615  * Besides the ranking of the node selector, every node gets assigned a node selection priority by the branching rule
3616  * that created the node. See the \ref BRANCHEXECLP and \ref BRANCHEXECPS callbacks of the branching rules for details.
3617  * For example, the node where the branching went in the same way as the deviation from the branching variable's
3618  * root solution could be assigned a higher priority than the node where the branching went in the opposite direction.
3619  *
3620  * The following methods provide access to the various types of leaf nodes:
3621  * - SCIPgetPrioChild() returns the child of the current node with the largest node selection priority, as assigned by the
3622  * branching rule.
3623  * If no child is available (for example, because the current node was pruned), a NULL pointer is returned.
3624  * - SCIPgetBestChild() returns the best child of the current node with respect to the node selector's ordering relation as
3625  * defined by the \ref NODESELCOMP callback. If no child is available, a NULL pointer is returned.
3626  * - SCIPgetPrioSibling() returns the sibling of the current node with the largest node selection priority.
3627  * If no sibling is available (for example, because all siblings of the current node have already been processed), a NULL
3628  * pointer is returned.
3629  * Note that in binary branching every node has at most one sibling, but since SCIP supports arbitrary branching rules,
3630  * this might not always be the case.
3631  * - SCIPgetBestSibling() returns the best sibling of the current node with respect to the node selector's ordering relation
3632  * as defined by the \ref NODESELCOMP callback. If no sibling is available, a NULL pointer is returned.
3633  * - SCIPgetBestNode() returns the best leaf from the tree (children, siblings, or other leaves) with respect to the node
3634  * selector's ordering relation as defined by the \ref NODESELCOMP callback. If no open leaf exists, a NULL pointer is
3635  * returned. In this case, the optimization is finished, and the node selector should return a NULL pointer as 'selnode'.
3636  * - SCIPgetBestboundNode() returns a leaf from the tree (children, siblings, or other leaves) with the smallest lower (dual)
3637  * objective bound. If the queue is empty, a NULL pointer is returned. In this case, the optimization is finished, and the
3638  * node selector should return a NULL pointer as 'selnode'.
3639  *
3640  *
3641  * @subsection NODESELCOMP
3642  *
3643  * The NODESELCOMP callback is called to compare two leaves of the current branching tree (say node 1 and node 2)
3644  * regarding their ordering relation.
3645  *
3646  * The NODESELCOMP should return the following values:
3647  * - value < 0, if node 1 comes before (is better than) node 2
3648  * - value = 0, if both nodes are equally good
3649  * - value > 0, if node 1 comes after (is worse than) node 2.
3650  *
3651  * @section NODESEL_ADDITIONALCALLBACKS Additional Callback Methods of a Node Selector
3652  *
3653  * The additional callback methods do not need to be implemented in every case. However, some of them have to be
3654  * implemented for most applications, they can be used, for example, to initialize and free private data.
3655  * Additional callbacks can either be passed directly with SCIPincludeNodesel() to SCIP or via specific
3656  * <b>setter functions</b> after a call of SCIPincludeNodeselBasic(), see also @ref NODESEL_INTERFACE.
3657  *
3658  * @subsection NODESELFREE
3659  *
3660  * If you are using node selector data, you have to implement this method in order to free the node selector data.
3661  * This can be done by the following procedure:
3662  * \code
3663  * static
3664  * SCIP_DECL_NODESELFREE(nodeselFreeMynodeselector)
3665  * {
3666  * SCIP_NODESELDATA* nodeseldata;
3667  *
3668  * nodeseldata = SCIPnodeselGetData(nodesel);
3669  * assert(nodeseldata != NULL);
3670  *
3671  * SCIPfreeMemory(scip, &nodeseldata);
3672  *
3673  * SCIPnodeselSetData(nodesel, NULL);
3674  *
3675  * return SCIP_OKAY;
3676  * }
3677  * \endcode
3678  * If you have allocated memory for fields in your node selector data, remember to free this memory
3679  * before freeing the node selector data itself.
3680  * If you are using the C++ wrapper class, this method is not available.
3681  * Instead, just use the destructor of your class to free the member variables of your class.
3682  *
3683  * @subsection NODESELINIT
3684  *
3685  * The NODESELINIT callback is executed after the problem is transformed.
3686  * The node selector may, e.g., use this call to initialize its node selector data.
3687  *
3688  * @subsection NODESELCOPY
3689  *
3690  * The NODESELCOPY callback is executed when a SCIP instance is copied, e.g. to
3691  * solve a sub-SCIP. By
3692  * defining this callback as
3693  * <code>NULL</code> the user disables the execution of the specified
3694  * node selector for all copied SCIP instances. This may deteriorate the performance
3695  * of primal heuristics using sub-SCIPs.
3696  *
3697  * @subsection NODESELEXIT
3698  *
3699  * The NODESELEXIT callback is executed before the transformed problem is freed.
3700  * In this method, the node selector should free all resources that have been allocated for the solving process
3701  * in NODESELINIT.
3702  *
3703  * @subsection NODESELINITSOL
3704  *
3705  * The NODESELINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3706  * begin.
3707  * The node selector may use this call to initialize its branch-and-bound specific data.
3708  *
3709  * @subsection NODESELEXITSOL
3710  *
3711  * The NODESELEXITSOL callback is executed before the branch-and-bound process is freed.
3712  * The node selector should use this call to clean up its branch-and-bound data.
3713  */
3714 
3715 
3716 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
3717 /**@page HEUR How to add primal heuristics
3718  *
3719  * Feasible solutions can be found in two different ways during the traversal of the branch-and-bound tree. On one
3720  * hand, the solution of a node's relaxation may be feasible with respect to the constraints (including the integrality).
3721  * On the other hand, feasible solutions can be discovered by primal heuristics.
3722  * \n
3723  * A complete list of all primal heuristics contained in this release can be found \ref PRIMALHEURISTICS "here".
3724  *
3725  * We now explain how users can add their own primal heuristics.
3726  * Take the simple and fast LP rounding heuristic (src/scip/heur_simplerounding.c) as an example.
3727  * The idea of simple rounding is to iterate over all fractional variables of an LP solution and round them down,
3728  * if the variables appears only with nonnegative coefficients in the system Ax <= b and round them up if
3729  * the variables appears only with nonpositive coefficients.
3730  * If one of both conditions applies for each of the fractional variables, this will give a feasible solution.
3731  * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjHeur wrapper
3732  * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_HEUR... callback methods.
3733  *
3734  * Additional documentation for the callback methods of a primal heuristic can be found in the file type_heur.h.
3735  *
3736  * Here is what you have to do to implement a primal heuristic:
3737  * -# Copy the template files src/scip/heur_xyz.c and src/scip/heur_xyz.h into files named "heur_myheuristic.c"
3738  * and "heur_myheuristic.h".
3739  * \n
3740  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
3741  * -# Use SCIPincludeHeurMyheuristic() in order to include the heuristic into your SCIP instance,
3742  * e.g., in the main file of your project (see, e.g., src/main.c in the Coloring example).
3743  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myheuristic".
3744  * -# Adjust the properties of the primal heuristic (see \ref HEUR_PROPERTIES).
3745  * -# Define the primal heuristic data (see \ref HEUR_DATA). This is optional.
3746  * -# Implement the interface methods (see \ref HEUR_INTERFACE).
3747  * -# Implement the fundamental callback methods (see \ref HEUR_FUNDAMENTALCALLBACKS).
3748  * -# Implement the additional callback methods (see \ref HEUR_ADDITIONALCALLBACKS). This is optional.
3749  *
3750  *
3751  * @section HEUR_PROPERTIES Properties of a Primal Heuristic
3752  *
3753  * At the top of the new file "heur_myheuristic.c" you can find the primal heuristic properties.
3754  * These are given as compiler defines.
3755  * In the C++ wrapper class, you have to provide the primal heuristic properties by calling the constructor
3756  * of the abstract base class scip::ObjHeur from within your constructor.
3757  * Of course, all of them are of relevant, but the most important ones for controlling the performance
3758  * are usually HEUR_FREQ and HEUR_TIMING.
3759  * The properties you have to set have the following meaning:
3760  *
3761  * \par HEUR_NAME: the name of the primal heuristic.
3762  * This name is used in the interactive shell to address the primal heuristic.
3763  * Additionally, if you are searching for a primal heuristic with SCIPfindHeur(), this name is looked up.
3764  * Names have to be unique: no two primal heuristics may have the same name.
3765  *
3766  * \par HEUR_DESC: the description of the primal heuristic.
3767  * This string is printed as a description of the primal heuristic in the interactive shell when you call "display heuristics".
3768  *
3769  * \par HEUR_DISPCHAR: the display character of the primal heuristic.
3770  * In the interactive shell, this character is printed in the first column of a status information row, if the primal
3771  * heuristic found the feasible solution belonging to the primal bound. Note that a star '*' stands for an integral
3772  * LP-relaxation.
3773  * In order to avoid confusion, display characters should be unique: no two primal heuristics should have the same display character.
3774  * You can get a list of all primal heuristics along with their display characters by entering "display heuristics" in the
3775  * SCIP interactive shell.
3776  *
3777  * \par HEUR_PRIORITY: the priority of the primal heuristic.
3778  * At each of the different entry points of the primal heuristics during the solving process (see HEUR_TIMING), they are
3779  * called in decreasing order of their priority.
3780  * \n
3781  * The priority of a primal heuristic should be set according to the complexity of the heuristic and the likelihood to find
3782  * feasible solutions: primal heuristics that provide fast algorithms that often succeed in finding a feasible solution should have
3783  * a high priority (like simple rounding). In addition, the interaction between different types of primal heuristics should be taken into account.
3784  * For example, improvement heuristics, which try to generate improved solutions by inspecting one or more of the feasible
3785  * solutions that have already been found, should have a low priority (like Crossover which by default needs at least 3 feasible solutions).
3786  *
3787  * \par HEUR_FREQ: the default frequency for executing the primal heuristic.
3788  * The frequency together with the frequency offset (see HEUR_FREQOFS) defines the depth levels at which the execution
3789  * method of the primal heuristic \ref HEUREXEC is called. For example, a frequency of 7 together with a frequency offset
3790  * of 5 means, that the \ref HEUREXEC callback is executed for subproblems that are in depth 5, 12, 19, ... of the branching tree. A
3791  * frequency of 0 together with a frequency offset of 3 means, that the execution method is only called at those nodes that are in
3792  * depth level 3 (i.e., at most for \f$2^3 = 8\f$ nodes if binary branching is applied).
3793  * Typical cases are: A frequency of 0 and an offset of 0 which means that
3794  * the heuristic is only called at the root node and a frequency of -1 which disables the heuristic.
3795  * \n
3796  * The frequency can be adjusted by the user. This property of the primal heuristic only defines the default value of the
3797  * frequency. If you want to have a more flexible control of when to execute the primal heuristic, you have to assign
3798  * a frequency of 1 and implement a check at the beginning of your execution method whether you really want to search for feasible
3799  * solutions or not. If you do not want to execute the method, set the result code to SCIP_DIDNOTRUN.
3800  *
3801  * \par HEUR_FREQOFS: the frequency offset for executing the primal heuristic.
3802  * The frequency offset defines the depth of the branching tree at which the primal heuristic is executed for the first
3803  * time. For example, a frequency of 7 (see HEUR_FREQ) together with a frequency offset of 10 means, that the
3804  * callback is executed for subproblems that are in depth 10, 17, 24, ... of the branching tree. In particular, assigning
3805  * different offset values to heuristics of the same type, like diving heuristics, can be useful for evenly spreading the
3806  * application of these heuristics across the branch-and-bound tree.
3807  * Note that if the frequency is equal to 1, the heuristic is applied for all nodes with depth level larger or equal to
3808  * the frequency offset.
3809  *
3810  * \par HEUR_MAXDEPTH: the maximal depth level for executing the primal heuristic.
3811  * This parameter denotes the maximal depth level in the branching tree up to which the execution method of the primal
3812  * heuristic is called. Use -1 for no limit (a usual case).
3813  *
3814  * \par HEUR_TIMING: the execution timing of the primal heuristic.
3815  * Primal heuristics have different entry points during the solving process and the execution timing parameter defines the
3816  * entry point at which the primal heuristic is executed first.
3817  * \n
3818  * The primal heuristic can be called first:
3819  * - before the processing of the node starts (SCIP_HEURTIMING_BEFORENODE)
3820  * - after each LP solve during the cut-and-price loop (SCIP_HEURTIMING_DURINGLPLOOP)
3821  * - after the cut-and-price loop was finished (SCIP_HEURTIMING_AFTERLPLOOP)
3822  * - after the processing of a node <em>with solved LP</em> was finished (SCIP_HEURTIMING_AFTERLPNODE)
3823  * - after the processing of a node <em>without solved LP</em> was finished (SCIP_HEURTIMING_AFTERPSEUDONODE)
3824  * - after the processing of the last node in the current plunge was finished, <em>and only if the LP was solved for
3825  * this node</em> (SCIP_HEURTIMING_AFTERLPPLUNGE)
3826  * - after the processing of the last node in the current plunge was finished, <em>and only if the LP was not solved
3827  * for this node</em> (SCIP_HEURTIMING_AFTERPSEUDOPLUNGE).
3828  * \par
3829  * A plunge is the successive solving of child and sibling nodes in the search tree.
3830  * The flags listed above can be combined to call the heuristic at multiple times by concatenating them with a bitwise OR.
3831  * Two useful combinations are already predefined:
3832  * - after the processing of a node was finished (SCIP_HEURTIMING_AFTERNODE; combines SCIP_HEURTIMING_AFTERLPNODE and
3833  * SCIP_HEURTIMING_AFTERPSEUDONODE)
3834  * - after the processing of the last node in the current plunge was finished (SCIP_HEURTIMING_AFTERPLUNGE; combines
3835  * SCIP_HEURTIMING_AFTERLPPLUNGE and SCIP_HEURTIMING_AFTERPSEUDOPLUNGE)
3836  * \par
3837  * Calling a primal heuristic "before the processing of the node starts" is particularly useful for heuristics
3838  * that do not need to access the LP solution of the current node. If such a heuristic finds a feasible solution, the
3839  * leaves of the branching tree exceeding the new primal bound are pruned. It may happen that even the current node can
3840  * be cut off without solving the LP relaxation. Combinatorial heuristics, like the farthest insert heuristic for the TSP
3841  * (see examples/TSP/src/HeurFarthestInsert.cpp), are often applicable at this point.
3842  * \n
3843  * Very fast primal heuristics that require an LP solution can also be called "after each LP solve during the
3844  * cut-and-price loop". Rounding heuristics, like the simple and fast LP rounding heuristic
3845  * (src/scip/heur_simplerounding.c), belong to this group of primal heuristics.
3846  * \n
3847  * Most heuristics, however, are called either after a node was completely processed
3848  * (e.g. expensive rounding heuristics like RENS), or even only after a full plunge was finished (e.g., diving heuristics).
3849  *
3850  * \par HEUR_USESSUBSCIP: Does the heuristic use a secondary SCIP instance?
3851  * Some heuristics and separators solve MIPs or SAT problems using a secondary SCIP instance. Examples are
3852  * Large Neighborhood Search heuristics such as RINS and Local Branching or the CGMIP separator. To avoid recursion,
3853  * these plugins usually deactivate all other plugins that solve MIPs. If a heuristic uses a secondary SCIP instance,
3854  * this parameter has to be TRUE and it is recommended to call SCIPsetSubscipsOff() for the secondary SCIP instance.
3855  *
3856  * Computational experiments indicate that for the overall performance of a MIP solver, it is important to evenly
3857  * spread the application of the heuristics across the branch-and-bound tree. Thus, the assignment of the parameters
3858  * HEUR_FREQ, HEUR_FREQOFS, and HEUR_TIMING should contribute to this aim.
3859  *
3860  * Note that all diving heuristics in the SCIP distribution (see, e.g., src/scip/heur_guideddiving.c) check whether other diving
3861  * heuristics have already been called at the current node. This can be done by comparing SCIPgetLastDivenode(scip) and
3862  * SCIPgetNNodes(scip). If the two are equal, and if the current node is not the root node (SCIPgetDepth(scip) > 0), diving
3863  * heuristics should be delayed by returning the result code 'SCIP_DELAYED'. This is an additional contribution to the goal of
3864  * not calling multiple similar heuristics at the same node.
3865  *
3866  *
3867  * @section HEUR_DATA Primal Heuristic Data
3868  *
3869  * Below the header "Data structures" you can find a struct which is called "struct SCIP_HeurData".
3870  * In this data structure, you can store the data of your primal heuristic. For example, you should store the adjustable
3871  * parameters of the primal heuristic or a working solution in this data structure.
3872  * If you are using C++, you can add primal heuristic data as usual as object variables to your class.
3873  * \n
3874  * Defining primal heuristic data is optional. You can leave the struct empty.
3875  *
3876  *
3877  * @section HEUR_INTERFACE Interface Methods
3878  *
3879  * At the bottom of "heur_myheuristic.c", you can find the interface method SCIPincludeHeurMyheuristic(),
3880  * which also appears in "heur_myheuristic.h"
3881  * SCIPincludeHeurMyheuristic() is called by the user, if (s)he wants to include the heuristic,
3882  * i.e., if (s)he wants to use the heuristic in his/her application.
3883  *
3884  * This method only has to be adjusted slightly.
3885  * It is responsible for notifying SCIP of the presence of the heuristic. For this, you can either call
3886  * SCIPincludeHeur(),
3887  * or SCIPincludeHeurBasic() since SCIP version 3.0. In the latter variant, \ref HEUR_ADDITIONALCALLBACKS "additional callbacks"
3888  * must be added via setter functions as, e.g., SCIPsetHeurCopy(). We recommend this latter variant because
3889  * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
3890  * variant must be manually adjusted with every SCIP release containing new callbacks for heuristics in order to compile.
3891  *
3892  * If you are using primal heuristic data, you have to allocate the memory for the data at this point.
3893  * You can do this by calling:
3894  * \code
3895  * SCIP_CALL( SCIPallocMemory(scip, &heurdata) );
3896  * \endcode
3897  * You also have to initialize the fields in struct SCIP_HeurData afterwards.
3898  *
3899  * You may also add user parameters for your primal heuristic, see the method SCIPincludeHeurFeaspump() in
3900  * src/scip/heur_oneopt.c for an example where a single Boolean parameter is added.
3901  *
3902  *
3903  * @section HEUR_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Primal Heuristic
3904  *
3905  * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
3906  * an operational algorithm.
3907  * They are passed together with the primal heuristic itself to SCIP using SCIPincludeHeur() or SCIPincludeHeurBasic(),
3908  * see @ref HEUR_INTERFACE.
3909  *
3910  *
3911  * Primal heuristic plugins have only one fundamental callback method, namely the HEUREXEC method.
3912  * This method has to be implemented for every primal heuristic; the other callback methods are optional.
3913  * In the C++ wrapper class scip::ObjHeur, the scip_exec() method (which corresponds to the HEUREXEC callback) is a virtual
3914  * abstract member function. You have to implement it in order to be able to construct an object of your primal heuristic
3915  * class.
3916  *
3917  * Additional documentation for the callback methods can be found in type_heur.h.
3918  *
3919  * @subsection HEUREXEC
3920  *
3921  * The HEUREXEC callback is called at different positions during the node processing loop, see HEUR_TIMING. It should
3922  * search for feasible solutions and add them to the solution pool. For creating a new feasible solution, the
3923  * methods SCIPcreateSol() and SCIPsetSolVal() can be used. Afterwards, the solution can be added to the storage by
3924  * calling the method SCIPtrySolFree() (or SCIPtrySol() and SCIPfreeSol()).
3925  *
3926  * The HEUREXEC callback gets a SCIP pointer, a pointer to the heuristic itself, the current point in the
3927  * solve loop and a result pointer as input (see type_heur.h).
3928  *
3929  * The heuristic has to set the result pointer appropriately!
3930  * Therefore it has the following options:
3931  * - finding at least one feasible solution (result SCIP_FOUNDSOL)
3932  * - stating that the primal heuristic searched, but did not find a feasible solution (result SCIP_DIDNOTFIND)
3933  * - stating that the primal heuristic was skipped (result SCIP_DIDNOTRUN)
3934  * - stating that the primal heuristic was skipped, but should be called again (result SCIP_DELAYED).
3935  *
3936  *
3937  * @section HEUR_ADDITIONALCALLBACKS Additional Callback Methods of a Primal Heuristic
3938  *
3939  * The additional callback methods do not need to be implemented in every case. However, some of them have to be
3940  * implemented for most applications, they can be used, for example, to initialize and free private data.
3941  * Additional callbacks can either be passed directly with SCIPincludeHeur() to SCIP or via specific
3942  * <b>setter functions</b> after a call of SCIPincludeHeurBasic(), see also @ref HEUR_INTERFACE.
3943  *
3944  * @subsection HEURFREE
3945  *
3946  * If you are using primal heuristic data, you have to implement this method in order to free the primal heuristic data.
3947  * This can be done by the following procedure:
3948  * \code
3949  * static
3950  * SCIP_DECL_HEURFREE(heurFreeMyheuristic)
3951  * {
3952  * SCIP_HEURDATA* heurdata;
3953  *
3954  * heurdata = SCIPheurGetData(heur);
3955  * assert(heurdata != NULL);
3956  *
3957  * SCIPfreeMemory(scip, &heurdata);
3958  *
3959  * SCIPheurSetData(heur, NULL);
3960  *
3961  * return SCIP_OKAY;
3962  * }
3963  * \endcode
3964  * If you have allocated memory for fields in your primal heuristic data, remember to free this memory
3965  * before freeing the primal heuristic data itself.
3966  * If you are using the C++ wrapper class, this method is not available.
3967  * Instead, just use the destructor of your class to free the member variables of your class.
3968  *
3969  * @subsection HEURINIT
3970  *
3971  * The HEURINIT callback is executed after the problem is transformed.
3972  * The primal heuristic may, e.g., use this call to initialize its primal heuristic data.
3973  *
3974  * @subsection HEURCOPY
3975  *
3976  * The HEURCOPY callback is executed when a SCIP instance is copied, e.g. to
3977  * solve a sub-SCIP. By
3978  * defining this callback as
3979  * <code>NULL</code> the user disables the execution of the specified
3980  * heuristic for all copied SCIP instances. This may deteriorate the performance
3981  * of primal heuristics using sub-SCIPs.
3982  *
3983  * @subsection HEUREXIT
3984  *
3985  * The HEUREXIT callback is executed before the transformed problem is freed.
3986  * In this method, the primal heuristic should free all resources that have been allocated for the solving process in
3987  * HEURINIT.
3988  *
3989  * @subsection HEURINITSOL
3990  *
3991  * The HEURINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
3992  * begin. The primal heuristic may use this call to initialize its branch-and-bound specific data.
3993  *
3994  * @subsection HEUREXITSOL
3995  *
3996  * The HEUREXITSOL callback is executed before the branch-and-bound process is freed. The primal heuristic should use this
3997  * call to clean up its branch-and-bound data, which was allocated in HEURINITSOL.
3998  */
3999 
4000 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4001 /**@page RELAX How to add relaxation handlers
4002  *
4003  * SCIP provides specific support for LP relaxations of constraint integer programs. In addition, relaxation handlers,
4004  * also called relaxators, can be used to include other relaxations, e.g. Lagrange relaxations or semidefinite
4005  * relaxations. The relaxation handler manages the necessary data structures and calls the relaxation solver to generate dual
4006  * bounds and primal solution candidates.
4007  * \n
4008  * However, the data to define a single relaxation must either be extracted by the relaxation handler itself (e.g., from
4009  * the user defined problem data, the LP information, or the integrality conditions), or be provided by the constraint
4010  * handlers. In the latter case, the constraint handlers have to be extended to support this specific relaxation.
4011  * \n
4012  *
4013  * We now explain how users can add their own relaxation handlers using the C interface. It is very easy to
4014  * transfer the C explanation to C++: whenever a method should be implemented using the SCIP_DECL_RELAX... notion,
4015  * reimplement the corresponding virtual member function of the abstract scip::ObjRelax wrapper base class.
4016  * Unfortunately, SCIP does not contain a default relaxation handler plugin, which could be used as an example.
4017  *
4018  * Additional documentation for the callback methods of a relaxation handler can be found in the file type_relax.h.
4019  *
4020  * Here is what you have to do to implement a relaxation handler:
4021  * -# Copy the template files src/scip/relax_xyz.c and src/scip/relax_xyz.h into files named "relax_myrelaxator.c"
4022  * and "relax_myrelaxator.h".
4023  * \n
4024  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
4025  * -# Use SCIPincludeRelaxMyrelaxator() in order to include the relaxation handler into your SCIP instance,
4026  * e.g, in the main file of your project (see, e.g., src/main.c in the Coloring example).
4027  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myrelaxator".
4028  * -# Adjust the properties of the relaxation handler (see \ref RELAX_PROPERTIES).
4029  * -# Define the relaxation handler data (see \ref RELAX_DATA). This is optional.
4030  * -# Implement the interface methods (see \ref RELAX_INTERFACE).
4031  * -# Implement the fundamental callback methods (see \ref RELAX_FUNDAMENTALCALLBACKS).
4032  * -# Implement the additional callback methods (see \ref RELAX_ADDITIONALCALLBACKS). This is optional.
4033  *
4034  *
4035  * @section RELAX_PROPERTIES Properties of a Relaxation Handler
4036  *
4037  * At the top of the new file "relax_myrelaxator.c" you can find the relaxation handler properties.
4038  * These are given as compiler defines.
4039  * In the C++ wrapper class, you have to provide the relaxation handler properties by calling the constructor
4040  * of the abstract base class scip::ObjRelax from within your constructor.
4041  * The properties you have to set have the following meaning:
4042  *
4043  * \par RELAX_NAME: the name of the relaxation handler.
4044  * This name is used in the interactive shell to address the relaxation handler.
4045  * Additionally, if you are searching for a relaxation handler with SCIPfindRelax(), this name is looked up.
4046  * Names have to be unique: no two relaxation handlers may have the same name.
4047  *
4048  * \par RELAX_DESC: the description of the relaxation handler.
4049  * This string is printed as a description of the relaxation handler in the interactive shell.
4050  *
4051  * \par RELAX_PRIORITY: the priority of the relaxation handler.
4052  * During each relaxation solving round, the included relaxation handlers and the
4053  * price-and-cut loop for solving the LP relaxation are called in a predefined order, which is given by the priorities
4054  * of the relaxation handlers.
4055  * First, the relaxation handlers with non-negative priority are called in the order of decreasing priority.
4056  * Next, the price-and-cut loop for solving the LP relaxation is executed.
4057  * Finally, the relaxation handlers with negative priority are called in the order of decreasing priority.
4058  * \n
4059  * Usually, you will have only one relaxation handler in your application and thus only have to decide whether it should
4060  * be called before or after solving the LP relaxation. For this decision you should consider the complexity of
4061  * the relaxation solving algorithm and the impact of the resulting solution: if your relaxation handler provides a fast
4062  * algorithm that usually has a high impact (i.e. the relaxation is a good approximation of the
4063  * feasible region of the subproblem and the solution severely improves the dual bound), it should have a non-negative
4064  * priority.
4065  * \n
4066  * Note that for certain applications, it is useful to disable the LP relaxation and only use your custom relaxation.
4067  * This can easily be achieved by setting the "lp/solvefreq" parameter to -1.
4068  *
4069  * \par RELAX_FREQ: the default frequency for solving the relaxation.
4070  * The frequency defines the depth levels at which the relaxation solving method \ref RELAXEXEC is called.
4071  * For example, a frequency of 7 means, that the relaxation solving callback is executed for subproblems that are in depth
4072  * 0, 7, 14, ... of the branching tree. A frequency of 0 means that the callback is only executed at the root node, i.e.,
4073  * only the relaxation of the root problem is solved. A frequency of -1 disables the relaxation handler.
4074  *
4075  *
4076  * @section RELAX_DATA Relaxation Handler Data
4077  *
4078  * Below the header "Data structures" you can find a struct which is called "struct SCIP_RelaxData".
4079  * In this data structure, you can store the data of your relaxation handler. For example, you should store the adjustable
4080  * parameters of the relaxation handler in this data structure.
4081  * If you are using C++, you can add relaxation handler data as usual as object variables to your class.
4082  * \n
4083  * Defining relaxation handler data is optional. You can leave the struct empty.
4084  *
4085  *
4086  * @section RELAX_INTERFACE Interface Methods
4087  *
4088  * At the bottom of "relax_myrelaxator.c", you can find the interface method SCIPincludeRelaxMyrelaxator(),
4089  * which also appears in "relax_myrelaxator.h".
4090  * SCIPincludeRelaxMyrelaxator() is called by the user, if (s)he wants to include the relaxation handler,
4091  * i.e., if (s)he wants to use the relaxation handler in his/her application.
4092  *
4093  * This method only has to be adjusted slightly.
4094  * It is responsible for notifying SCIP of the presence of the relaxation handler. For this, you can either call
4095  * SCIPincludeRelax(),
4096  * or SCIPincludeRelaxBasic() since SCIP version 3.0. In the latter variant, \ref RELAX_ADDITIONALCALLBACKS "additional callbacks"
4097  * must be added via setter functions as, e.g., SCIPsetRelaxCopy(). We recommend this latter variant because
4098  * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
4099  * variant must be manually adjusted with every SCIP release containing new callbacks for relaxation handlers in order to compile.
4100  *
4101  * If you are using relaxation handler data, you have to allocate the memory for the data at this point.
4102  * You can do this by calling:
4103  * \code
4104  * SCIP_CALL( SCIPallocMemory(scip, &relaxdata) );
4105  * \endcode
4106  * You also have to initialize the fields in struct SCIP_RelaxData afterwards.
4107  *
4108  * You may also add user parameters for your relaxation handler, see the method SCIPincludeConshdlrKnapsack() in
4109  * the \ref cons_knapsack.h "knapsack constraint handler" for an example of how to add user parameters.
4110  *
4111  *
4112  * @section RELAX_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Relaxation Handler
4113  *
4114  * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
4115  * an operational algorithm.
4116  * They are passed together with the relaxation handler itself to SCIP using SCIPincludeRelax() or SCIPincludeRelaxBasic(),
4117  * see @ref RELAX_INTERFACE.
4118  *
4119  *
4120  * Relaxation handler plugins have only one fundamental callback method, namely the \ref RELAXEXEC method.
4121  * This method has to be implemented for every relaxation handler; the other callback methods are optional.
4122  * In the C++ wrapper class scip::ObjRelax, the scip_exec() method (which corresponds to the \ref RELAXEXEC callback) is a virtual
4123  * abstract member function.
4124  * You have to implement it in order to be able to construct an object of your relaxation handler class.
4125  *
4126  * Additional documentation for the callback methods can be found in type_relax.h.
4127  *
4128  * @subsection RELAXEXEC
4129  * The RELAXEXEC is called in each relaxation solving round. It should solve the current
4130  * subproblem's relaxation.
4131  *
4132  * Note that, like the LP relaxation, the relaxation handler should only operate on variables for which the corresponding
4133  * column exists in the transformed problem. Typical methods called by a relaxation handler are SCIPconstructLP() and SCIPflushLP() to
4134  * make sure that the LP of the current node is constructed and its data can be accessed via calls to SCIPgetLPRowsData()
4135  * and SCIPgetLPColsData(), SCIPseparateSol() to call the cutting plane separators for a given primal solution, and
4136  * SCIPupdateLocalLowerbound() to update the current node's dual bound after having solved the relaxation.
4137  * In addition, you may want to call SCIPtrySolFree() if you think that you have found a feasible primal solution.
4138  *
4139  * The primal solution of the relaxation can be stored inside the data structures of SCIP with
4140  * <code>SCIPsetRelaxSolVal()</code> and <code>SCIPsetRelaxSolVals()</code> and later accessed by
4141  * <code>SCIPgetRelaxSolVal()</code>.
4142  * Furthermore, there is a list of external branching candidates, that can be filled by relaxation handlers and constraint handlers,
4143  * allowing branching rules to take these candidates as a guide on how to split the problem into subproblems.
4144  * Relaxation handlers should store appropriate candidates in this list using the method <code>SCIPaddExternBranchCand()</code>.
4145  *
4146  * Usually, the RELAXEXEC callback only solves the relaxation and provides a lower (dual) bound with a call to
4147  * SCIPupdateLocalLowerbound().
4148  * However, it may also produce domain reductions, add additional constraints or generate cutting planes. It has the
4149  * following options:
4150  * - detecting that the node is infeasible in the variable's bounds and can be cut off (result SCIP_CUTOFF)
4151  * - adding an additional constraint and stating that the relaxation handler should not be called again on the same
4152  * relaxation (result SCIP_CONSADDED)
4153  * - reducing a variable's domain and stating that the relaxation handler should not be called again on the same
4154  * relaxation (result SCIP_REDUCEDDOM)
4155  * - adding a cutting plane to the LP and stating that the relaxation handler should not be called again on the same
4156  * relaxation (result SCIP_SEPARATED)
4157  * - stating that the relaxation handler solved the relaxation and should not be called again on the same relaxation
4158  * (result SCIP_SUCCESS)
4159  * - interrupting the solving process to wait for additional input, e.g., cutting planes (result SCIP_SUSPENDED)
4160  * - stating that the separator was skipped (result SCIP_DIDNOTRUN).
4161  *
4162  * In the above criteria, "the same relaxation" means that the LP relaxation stayed unmodified. This means in particular
4163  * that no row has been added and no bounds have been modified. For example, changing the bounds of a variable will, as
4164  * long as it was a COLUMN variable, lead to a modification in the LP such that the relaxation handler is called again
4165  * after it returned with the result code SCIP_REDUCEDDOM.
4166  *
4167  *
4168  * @section RELAX_ADDITIONALCALLBACKS Additional Callback Methods of a Relaxation Handler
4169  *
4170  * The additional callback methods do not need to be implemented in every case. However, some of them have to be
4171  * implemented for most applications, they can be used, for example, to initialize and free private data.
4172  * Additional callbacks can either be passed directly with SCIPincludeRelax() to SCIP or via specific
4173  * <b>setter functions</b> after a call of SCIPincludeRelaxBasic(), see also @ref RELAX_INTERFACE.
4174  *
4175  * @subsection RELAXFREE
4176  *
4177  * If you are using relaxation handler data, you have to implement this method in order to free the relaxation handler
4178  * data. This can be done by the following procedure:
4179  * \code
4180  * static
4181  * SCIP_DECL_RELAXFREE(relaxFreeMyrelaxator)
4182  * {
4183  * SCIP_RELAXDATA* relaxdata;
4184  *
4185  * relaxdata = SCIPrelaxGetData(relax);
4186  * assert(relaxdata != NULL);
4187  *
4188  * SCIPfreeMemory(scip, &relaxdata);
4189  *
4190  * SCIPrelaxSetData(relax, NULL);
4191  *
4192  * return SCIP_OKAY;
4193  * }
4194  * \endcode
4195  * If you have allocated memory for fields in your relaxation handler data, remember to free this memory
4196  * before freeing the relaxation handler data itself.
4197  * If you are using the C++ wrapper class, this method is not available.
4198  * Instead, just use the destructor of your class to free the member variables of your class.
4199  *
4200  * @subsection RELAXINIT
4201  *
4202  * The RELAXINIT callback is executed after the problem is transformed.
4203  * The relaxation handler may, e.g., use this call to initialize its relaxation handler data.
4204  *
4205  * @subsection RELAXCOPY
4206  *
4207  * The RELAXCOPY callback is executed when a SCIP instance is copied, e.g. to
4208  * solve a sub-SCIP. By
4209  * defining this callback as
4210  * <code>NULL</code> the user disables the execution of the specified
4211  * relaxation handler for all copied SCIP instances. This may deteriorate the performance
4212  * of primal heuristics using sub-SCIPs.
4213  *
4214  * @subsection RELAXEXIT
4215  *
4216  * The RELAXEXIT callback is executed before the transformed problem is freed.
4217  * In this method, the relaxation handler should free all resources that have been allocated for the solving process in
4218  * RELAXINIT.
4219  *
4220  * @subsection RELAXINITSOL
4221  *
4222  * The RELAXINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
4223  * begin. The relaxation handler may use this call to initialize its branch-and-bound specific data.
4224  *
4225  * @subsection REALXEXITSOL
4226  *
4227  * The RELAXEXITSOL callback is executed before the branch-and-bound process is freed.
4228  * The relaxation handler should use this call to clean up its branch-and-bound data.
4229  */
4230 
4231 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4232 /**@page READER How to add file readers
4233  *
4234  * Mainly, file readers are called to parse an input file and generate a constraint integer programming model. They
4235  * create constraints and variables and activate variable pricers if necessary. However, they can also be called, for
4236  * example, to parse an input file containing information about a primal solution or fixing of variables. Besides that
4237  * it is possible to use some of them for writing (exporting) the problem in a specific format. \n A complete list of
4238  * all file readers contained in this release can be found \ref FILEREADERS "here".
4239  *
4240  * Since a file reader is also responsible for writing a file, the user may
4241  * ask why the readers have not the name "filehandler". This name would
4242  * represent this plugin much better than the used one.
4243  * \n
4244  * The used name "readers" is historically grown. In the beginning of SCIP
4245  * there was no need to write/export problems. Therefore, the the plugin
4246  * name "readers" was best fitting for this plugin since only reading was essential.
4247  * It turned out, however, that it is quite nice to write/export certain subproblem during
4248  * the solving process mainly for debugging. Therefore, a writing callback
4249  * was added to the "readers" plugin.
4250  *
4251  * We now explain how users can add their own file readers.
4252  * Take the file reader for MIPs in IBM's Mathematical Programming System format (src/scip/reader_mps.c) as an example.
4253  * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjReader wrapper
4254  * base class and implement the scip_...() virtual methods instead of the SCIP_DECL_READER... callback methods.
4255  *
4256  * Additional documentation for the callback methods of a file reader can be found in the file type_reader.h.
4257  *
4258  * Here is what you have to do to implement a file reader named "myreader" in C:
4259  * -# Copy the template files src/scip/reader_xyz.c and src/scip/reader_xyz.h into files named
4260  * "reader_myreader.c" and "reader_myreader.h".
4261  * \n
4262  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
4263  * -# Use SCIPincludeReaderMyreader() in order to include the file reader into your SCIP instance,
4264  * e.g., in the main file of your project (see, e.g., src/main.c in the Coloring example).
4265  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myreader".
4266  * -# Adjust the \ref READER_PROPERTIES "properties of the file reader".
4267  * -# Define the \ref READER_DATA "file reader data". This is optional.
4268  * -# Implement the \ref READER_INTERFACE "interface methods".
4269  * -# Implement the \ref READER_FUNDAMENTALCALLBACKS "fundamental callback methods".
4270  * -# Implement the \ref READER_ADDITIONALCALLBACKS "additional callback methods". This is optional.
4271  *
4272  *
4273  * @section READER_PROPERTIES Properties of a File Reader
4274  *
4275  * At the top of the new file "reader_myreader.c" you can find the file reader properties.
4276  * These are given as compiler defines.
4277  * In the C++ wrapper class, you have to provide the file reader properties by calling the constructor
4278  * of the abstract base class scip::ObjReader from within your constructor.
4279  * The properties you have to set have the following meaning:
4280  *
4281  * \par READER_NAME: the name of the file reader.
4282  * This name is used in the interactive shell to address the file reader.
4283  * Additionally, if you are searching for a file reader with SCIPfindReader(), this name is looked up.
4284  * Names have to be unique: no two file readers may have the same name.
4285  *
4286  * \par READER_DESC: the description of the file reader.
4287  * This string is printed as a description of the file reader in the interactive shell.
4288  *
4289  * \par READER_EXTENSION: the file name extension of the file reader.
4290  * Each file reader is hooked to a single file name extension. It is automatically called if the user wants to read in a
4291  * file of corresponding name. The extensions of the different file readers have to be unique.
4292  * Note that the additional extension '.gz', '.z', or '.Z' (indicating a gzip compressed file) are ignored for assigning
4293  * an input file to a reader.
4294  * \n
4295  * It is not possible to hook up a (single) file reader with more than one file extension.
4296  * It is, however, not necessary to implement the same (parsing/writing) methods more than once, if you want to
4297  * support several file extension with the same parser. To do so look at the files reader_lp.c
4298  * and reader_rlp.c. Both support the LP format.
4299  *
4300  *
4301  * @section READER_DATA File Reader Data
4302  *
4303  * Below the header "Data structures" you can find a struct which is called "struct SCIP_ReaderData".
4304  * In this data structure, you can store the data of your file reader. For example, you should store the adjustable
4305  * parameters of the file reader in this data structure.
4306  * If you are using C++, you can add file reader data as usual as object variables to your class.
4307  * \n
4308  * Defining file reader data is optional. You can leave the struct empty.
4309  *
4310  *
4311  * @section READER_INTERFACE Interface Methods
4312  *
4313  * At the bottom of "reader_myreader.c", you can find the interface method SCIPincludeReaderMyreader(),
4314  * which also appears in "reader_myreader.h".
4315  * SCIPincludeReaderMyreader() is called by the user, if (s)he wants to include the reader,
4316  * i.e., if (s)he wants to use the reader in his/her application.
4317  *
4318  * This method only has to be adjusted slightly.
4319  * It is responsible for notifying SCIP of the presence of the reader. For this, you can either call
4320  * SCIPincludeReader(),
4321  * or SCIPincludeReaderBasic() since SCIP version 3.0. In the latter variant, \ref READER_ADDITIONALCALLBACKS "additional callbacks"
4322  * must be added via setter functions as, e.g., SCIPsetReaderCopy(). We recommend this latter variant because
4323  * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
4324  * variant must be manually adjusted with every SCIP release containing new callbacks for readers in order to compile.
4325  *
4326  * If you are using file reader data, you have to allocate the memory for the data at this point.
4327  * You can do this by calling:
4328  * \code
4329  * SCIP_CALL( SCIPallocMemory(scip, &readerdata) );
4330  * \endcode
4331  * You also have to initialize the fields in struct SCIP_ReaderData afterwards.
4332  *
4333  * You may also add user parameters for your file reader, see the method SCIPincludeReaderLp() in
4334  * src/scip/reader_lp.c for an example.
4335  *
4336  *
4337  * @section READER_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a File Reader
4338  *
4339  * File reader plugins have no fundamental callback methods. This is due to
4340  * the fact that a file reader can be used for reading and/or writing a
4341  * file. A file reader is only useful if the reader method \ref READERREAD
4342  * and/or the writing method \ref READERWRITE is implemented. One of these
4343  * methods should be implemented for every file reader; the other callback
4344  * methods \ref READERCOPY and \ref READERFREE are optional. In the C++ wrapper class scip::ObjReader, the
4345  * scip_read() and scip_write() methods (which corresponds to the \ref
4346  * READERREAD and \ref READERWRITE callback) are virtual member
4347  * functions. At least one of them should be implemented.
4348  *
4349  * Additional documentation for the callback methods can be found in type_reader.h.
4350  *
4351  *
4352  * @section READER_ADDITIONALCALLBACKS Additional Callback Methods of a File Reader
4353  *
4354  * Additional callbacks can either be passed directly with SCIPincludeReader() to SCIP or via specific
4355  * <b>setter functions</b> after a call of SCIPincludeReaderBasic(), see also @ref READER_INTERFACE.
4356  *
4357  *
4358  * File reader plugins contain only additional callback methods, namely the methods \ref READERREAD,
4359  * \ref READERWRITE, \ref READERFREE, and \ref READERCOPY. Therefore, these are not needed to be implemented. However,
4360  * at least \ref READERREAD and/or \ref READERWRITE should be implemented (see notes
4361  * \ref READER_FUNDAMENTALCALLBACKS "above").
4362  *
4363  *
4364  * @subsection READERREAD
4365  *
4366  * The READERREAD callback is called when the user invokes SCIP to read in a file with file name extension
4367  * corresponding to the READER_EXTENSION property of the file reader. This is usually triggered by a call to the method
4368  * SCIPreadProb() or by an interactive shell command.
4369  * The READERREAD callback should parse the input file and perform the desired action, which usually means
4370  * generating a constraint integer programming model, adding a primal solution, fixing variables
4371  * in an existing model.
4372  * \n
4373  * Typical methods called by a file reader that is used to read/generate constraint
4374  * integer programming models are, for example,
4375  *
4376  * - creating an empty problem: SCIPcreateProb()
4377  * - creating the variables: SCIPcreateVar(), SCIPchgVarType(), SCIPchgVarLb(), SCIPchgVarUb(), SCIPaddVar(), and
4378  * SCIPreleaseVar()
4379  * - modifying the objective function: SCIPchgVarObj() and SCIPsetObjsense().
4380  * - creating the constraints: SCIPcreateConsLinear(), SCIPaddCoefLinear(), SCIPchgLhsLinear(), SCIPchgRhsLinear(),
4381  * SCIPaddCons(), and SCIPreleaseCons()
4382  *
4383  * Primal solutions can only be created for the transformed problem. Therefore, the user has to call SCIPtransformProb()
4384  * before (s)he reads in the file containing the solution and adds it to the solution pool via the method SCIPreadSol().
4385  *
4386  *
4387  * @subsection READERWRITE
4388  *
4389  * The READERWRITE callback is called when the user invokes SCIP to write a problem (original or transformed)
4390  * in the format the reader supports. This is only possible if this callback is implemented. To write the problem
4391  * all necessary information is given through the parameters of this callback method (see type_reader.h). This
4392  * information should be used to output the problem in the requested format. This callback method is usually
4393  * triggered by the call of the methods SCIPwriteOrigProblem(), SCIPwriteTransProblem(), SCIPprintOrigProblem(),
4394  * or SCIPprintTransProblem().
4395  * \n
4396  * A typical method called by a file reader which is used to write/export a constraint
4397  * integer programming model is SCIPinfoMessage(). This method outputs a given string into a file
4398  * or into stdout.
4399  * \n
4400  * For an example we refer to the writing method of the MPS reader (see reader_mps.c).
4401  *
4402  *
4403  * @subsection READERCOPY
4404  *
4405  * The READERCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
4406  * callback as <code>NULL</code> the user disables the execution of the specified reader for all copied SCIP
4407  * instances. The question might arise why to copy that plugin. In case of debugging it is nice to be able to
4408  * write/display the copied instances. Since the reader is in charge of that, you might want to copy the plugin. Below
4409  * you see a standard implementation.
4410  *
4411  * \code
4412  * static
4413  * SCIP_DECL_READERCOPY(readerCopyMyreader)
4414  * {
4415  * assert(scip != NULL);
4416  * assert(reader != NULL);
4417  * assert(strcmp(SCIPreaderGetName(reader), READER_NAME) == 0);
4418  *
4419  * SCIP_CALL( SCIPincludeReaderMyreader(scip) );
4420  *
4421  * return SCIP_OKAY;
4422  * }
4423  * \endcode
4424  *
4425  * @subsection READERFREE
4426  *
4427  * If you are using file reader data, you have to implement this method in order to free the file reader data.
4428  * This can be done by the following procedure:
4429  * \code
4430  * static
4431  * SCIP_DECL_READERFREE(readerFreeMyreader)
4432  * {
4433  * SCIP_READERDATA* readerdata;
4434  *
4435  * readerdata = SCIPreaderGetData(reader);
4436  * assert(readerdata != NULL);
4437  *
4438  * SCIPfreeMemory(scip, &readerdata);
4439  *
4440  * SCIPreaderSetData(reader, NULL);
4441  *
4442  * return SCIP_OKAY;
4443  * }
4444  * \endcode
4445  * If you have allocated memory for fields in your file reader data, remember to free this memory
4446  * before freeing the file reader data itself.
4447  * If you are using the C++ wrapper class, this method is not available.
4448  * Instead, just use the destructor of your class to free the member variables of your class.
4449  *
4450  */
4451 
4452 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4453 /**@page DIALOG How to add dialogs
4454  *
4455  * SCIP comes with a command line shell which allows the user to read in problem instances, modify the solver's
4456  * parameters, initiate the optimization and display certain statistics and solution information. This shell consists
4457  * of dialogs, which are organized as a tree in SCIP. A node of this tree which is not a leaf represents a menu in
4458  * the shell and the children of this node correspond to the entries of this menu (which can again be menus). All
4459  * different dialogs are managed by a dialog handler, which, in particular, is responsible for executing the dialog
4460  * corresponding to the user's command in the shell. The concept of a dialog handler is different to that
4461  * of a constraint handler, which is used to manage objects of the same structure, see \ref CONS. In particular, SCIP
4462  * features only one dialog handler (dialog_default.h), whereas there may exist different constraint handlers.
4463  * \n
4464  * A complete list of all dialogs contained in this release can be found \ref DIALOGS "here".
4465  *
4466  * We now explain how users can extend the interactive shell by adding their own dialog.
4467  * We give the explanation for creating your own source file for each additional dialog. Of course, you can collect
4468  * different dialogs in one source file. Take src/scip/dialog_default.c, where all default dialog plugins are collected, as an
4469  * example.
4470  * As all other default plugins, the default dialog plugin and the template dialog are written in C. C++ users can easily
4471  * adapt the code by using the scip::ObjDialog wrapper base class and implement the scip_...() virtual methods instead of the
4472  * SCIP_DECL_DIALOG... callback methods.
4473  *
4474  * Additional documentation for the callback methods of a dialog can be found in the file type_dialog.h.
4475  *
4476  * Here is what you have to do to add a dialog (assuming your dialog is named "mydialog"):
4477  * -# Copy the template files src/scip/dialog_xyz.c and src/scip/dialog_xyz.h into files named "dialog_mydialog.c"
4478  * and "dialog_mydialog.h".
4479  * \n
4480  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
4481  * -# Use SCIPincludeDialogMydialog() in order to include the dialog handler into your SCIP instance,
4482  * e.g., in the main file of your project (see, e.g., src/main.c in the Coloring example).
4483  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mydialog".
4484  * -# Adjust the \ref DIALOG_PROPERTIES "properties of the dialog".
4485  * -# Define the \ref DIALOG_DATA "dialog data". This is optional.
4486  * -# Implement the \ref DIALOG_INTERFACE "interface methods".
4487  * -# Implement the \ref DIALOG_FUNDAMENTALCALLBACKS "fundamental callback methods".
4488  * -# Implement the \ref DIALOG_ADDITIONALCALLBACKS "additional callback methods". This is optional.
4489  *
4490  *
4491  * @section DIALOG_PROPERTIES Properties of a Dialog
4492  *
4493  * At the top of the new file "dialog_mydialog.c" you can find the dialog properties.
4494  * These are given as compiler defines.
4495  * In the C++ wrapper class, you have to provide the dialog properties by calling the constructor
4496  * of the abstract base class scip::ObjDialog from within your constructor.
4497  * The properties you have to set have the following meaning:
4498  *
4499  * \par DIALOG_NAME: the name of the dialog.
4500  * In the interactive shell, this name appears as the command name of the dialog in the parent dialog.
4501  * Additionally, if you are searching an entry in a menu with SCIPdialogFindEntry(), this name is looked up.
4502  * Names within one menu have to be unique: no two dialogs in the same menu may have the same name.
4503  *
4504  * \par DIALOG_DESC: the description of the dialog.
4505  * This string is printed as a description of the dialog in the interactive shell if the additional
4506  * callback method \ref DIALOGDESC is not implemented.
4507  *
4508  * \par DIALOG_ISSUBMENU: whether the dialog is a (sub)menu.
4509  * This parameter states whether the dialog is a menu in the interactive shell, i.e., is the parent of further
4510  * dialogs.
4511  *
4512  *
4513  * @section DIALOG_DATA Dialog Data
4514  *
4515  * Below the header "Data structures" you can find a struct which is called "struct SCIP_DialogData".
4516  * In this data structure, you can store the data of your dialog.
4517  * If you are using C++, you can add dialog data as usual as object variables to your class.
4518  * \n
4519  * Defining dialog data is optional. You can leave the struct empty.
4520  *
4521  *
4522  * @section DIALOG_INTERFACE Interface Methods
4523  *
4524  * At the bottom of "dialog_mydialog.c" you can find the interface method SCIPincludeDialogMydialog(), which also appears
4525  * in "dialog_mydialog.h".
4526  * \n
4527  * This method only has to be adjusted slightly.
4528  * It is responsible for notifying SCIP of the presence of the dialog, which can be done by the following lines of code:
4529  * \code
4530  * if( !SCIPdialogHasEntry(parentdialog, DIALOG_NAME) )
4531  * {
4532  * SCIP_CALL( SCIPcreateDialog(scip, &dialog, dialogExecMydialog, dialogDescMydialog, dialogFreeMydialog,
4533  * DIALOG_NAME, DIALOG_DESC, DIALOG_ISSUBMENU, dialogdata) );
4534  *
4535  * SCIP_CALL( SCIPaddDialogEntry(scip, parentdialog, dialog) );
4536  *
4537  * SCIP_CALL( SCIPreleaseDialog(scip, &dialog) );
4538  * }
4539  * \endcode
4540  * Here "parentdialog" has to be an existing dialog which is defined to be a menu (see DIALOG_ISSUBMENU), e.g.,
4541  * the default root dialog. The method SCIPgetRootDialog() returns the root dialog.
4542  *
4543  * The interface method is called by the user, if (s)he wants to include the dialog, i.e., if (s)he wants to use the dialog in
4544  * his/her application.
4545  * Note that in order to be able to link the new dialog to an existing default dialog
4546  * (except the root dialog) it has to be included <b>after the
4547  * default dialogs plugin</b>, i.e., the SCIPincludeDialogMydialog() call has to occur after the
4548  * SCIPincludeDialogDefault() call. The SCIPincludeDialogDefault() method is called from within the SCIPincludeDefaultPlugins()
4549  * method. Therefore, it suffices to include your dialog plugins after you have called SCIPincludeDefaultPlugins().
4550  * In case you want to add a dialog to the <b>root dialog</b>, you just use the following
4551  * lines of code to get/create the root dialog.
4552  *
4553  * \code
4554  * SCIP_DIALOG* root;
4555  *
4556  * root = SCIPgetRootDialog(scip);
4557  * if( root == NULL )
4558  * {
4559  * SCIP_CALL( SCIPcreateRootDialog(scip, &root) );
4560  * }
4561  * assert( root != NULL );
4562  * \endcode
4563  *
4564  * Therefore, in this case you do not have to worry about the calls of
4565  * SCIPincludeDialogDefault() and SCIPincludeDefaultPlugins() .
4566  *
4567  * If you are using dialog data, you have to allocate the memory for the data at this point.
4568  * You can do this by calling:
4569  * \code
4570  * SCIP_CALL( SCIPallocMemory(scip, &dialogdata) );
4571  * \endcode
4572  * You also have to initialize the fields in struct SCIP_DialogData afterwards.
4573  *
4574  * Consider the following example. The user wants to add a "drawgraph" command to the root menu of SCIP.
4575  * (S)he copies the "dialog_xyz.c" and "dialog_xyz.h" files into files "dialog_drawgraph.c" and "dialog_drawgraph.h", respectively.
4576  * Then, (s)he puts the following code into the SCIPincludeDialogDrawgraph() method, compare SCIPincludeDialogDefault() in
4577  * src/scip/dialog_default.c:
4578  * \code
4579  * SCIP_RETCODE SCIPincludeDialogDrawgraph(
4580  * SCIP* scip
4581  * )
4582  * {
4583  * SCIP_DIALOG* root;
4584  * SCIP_DIALOG* dialog;
4585  *
4586  * root = SCIPgetRootDialog(scip);
4587  * if( root == NULL )
4588  * {
4589  * SCIP_CALL( SCIPcreateRootDialog(scip, &root) );
4590  * }
4591  * assert( root != NULL );
4592  *
4593  * if( !SCIPdialogHasEntry(root, "drawgraph") )
4594  * {
4595  * SCIP_CALL( SCIPcreateDialog(scip, &dialog, SCIPdialogExecDrawgraph, NULL, NULL,
4596  * "drawgraph", "draws the graph for the current problem instance", FALSE, NULL) );
4597  * SCIP_CALL( SCIPaddDialogEntry(scip, root, dialog) );
4598  * SCIP_CALL( SCIPreleaseDialog(scip, &dialog) );
4599  * }
4600  *
4601  * return SCIP_OKAY;
4602  * }
4603  * \endcode
4604  *
4605  * Using this code, it is even possible to call SCIPincludeDialogDrawgraph() before including the default dialog plugins,
4606  * and you can also call it multiple times without causing inconsistencies in the dialog structure.
4607  *
4608  *
4609  * @section DIALOG_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Dialog
4610  *
4611  * Dialogs have only one fundamental callback method, namely the \ref DIALOGEXEC method.
4612  * This method has to be implemented for every dialog; the other callback methods are optional.
4613  * In the C++ wrapper class scip::ObjDialog, the scip_exec() method (which corresponds to the \ref DIALOGEXEC callback) is a virtual
4614  * abstract member function.
4615  * You have to implement it in order to be able to construct an object of your dialog class.
4616  *
4617  * Additional documentation for the callback methods can be found in type_dialog.h.
4618  *
4619  * @subsection DIALOGEXEC
4620  *
4621  * The DIALOGEXEC method is invoked, if the user selected the dialog's command name in the parent's menu. It should
4622  * execute what is stated in DIALOG_DESC, e.g., the display constraint handlers dialog should display information about
4623  * the constraint handlers included in SCIP, see src/scip/dialog_default.c.
4624  *
4625  * For typical methods called by the execution method, have a look at src/scip/dialog_default.c.
4626  *
4627  * The callback has to return which dialog should be processed next. This can be, for example, the root dialog
4628  * (SCIPdialoghdlrGetRoot()), the parent dialog (SCIPdialogGetParent()) or NULL, which stands for closing the interactive
4629  * shell.
4630  *
4631  *
4632  * @section DIALOG_ADDITIONALCALLBACKS Additional Callback Methods of a Dialog
4633  *
4634  * The additional callback methods do not need to be implemented in every case.
4635  * They can be used, for example, to free private data.
4636  *
4637  * @subsection DIALOGPFREE
4638  *
4639  * If you are using dialog data, you have to implement this method in order to free the dialog data.
4640  * This can be done by the following procedure:
4641  * \code
4642  * static
4643  * SCIP_DECL_DIALOGFREE(dialogFreeMydialog)
4644  * {
4645  * SCIP_DIALOGDATA* dialogdata;
4646  *
4647  * dialogdata = SCIPdialogGetData(dialog);
4648  * assert(dialogdata != NULL);
4649  *
4650  * SCIPfreeMemory(scip, &dialogdata);
4651  *
4652  * SCIPdialogSetData(dialog, NULL);
4653  *
4654  * return SCIP_OKAY;
4655  * }
4656  * \endcode
4657  * If you have allocated memory for fields in your dialog data, remember to free this memory
4658  * before freeing the dialog data itself.
4659  * If you are using the C++ wrapper class, this method is not available.
4660  * Instead, just use the destructor of your class to free the member variables of your class.
4661  *
4662  * @subsection DIALOGDESC
4663  *
4664  * This method is called when the help menu of the parent is displayed. It should output (usually a single line of)
4665  * information describing the meaning of the dialog.
4666  * \n
4667  * If this callback is not implemented, the description string of the dialog (DIALOG_DESC) is displayed instead.
4668  *
4669  * @subsection DIALOGCOPY
4670  *
4671  * The DIALOGCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
4672  * callback as <code>NULL</code> the user disables the execution of this dialog for all copied SCIP instances. In
4673  * general there is no need to copy any dialog since it is most unlikely to start the interactive shell of the copied
4674  * instances.
4675  *
4676  */
4677 
4678 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4679 /**@page DISP How to add display columns
4680  *
4681  * While solving a constraint integer program, SCIP displays status information in a column-like fashion. The current
4682  * number of processed branching tree nodes, the solving time, and the relative gap between primal and dual bound are
4683  * examples of such display columns. There already exists a wide variety of display columns which can be activated or
4684  * deactivated on demand, see src/scip/disp_default.c. Additionally, the user can implement his/her own display columns
4685  * in order to track problem or algorithm specific values.
4686  * \n
4687  * A complete list of all displays contained in this release can be found \ref DISPLAYS "here".
4688  *
4689  * We now explain users can add their own display columns.
4690  * We give the explanation for creating your own source file for each additional display column. Of course, you can collect
4691  * different additional display columns in one source file.
4692  * Take src/scip/disp_default.c, where all default display columns are collected, as an example.
4693  * As all other default plugins, the default display column plugins and the display column template are written in C.
4694  * C++ users can easily adapt the code by using the scip::ObjDisp wrapper base class and implement the scip_...() virtual methods
4695  * instead of the SCIP_DECL_DISP... callback methods.
4696  *
4697  *
4698  * Additional documentation for the callback methods of a display column can be found in the file type_disp.h.
4699  *
4700  * Here is what you have to do to implement a display column (assuming your display column is named "mydisplaycolumn"):
4701  * -# Copy the template files src/scip/disp_xyz.c and src/scip/disp_xyz.h into files named "disp_mydisplaycolumn.c"
4702  * and "disp_mydisplaycolumn.h".
4703  \n
4704  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
4705  * -# Use SCIPincludeDispMydisplaycolumn() in order to include the display column into your SCIP instance,
4706  * e.g., in the main file of your project (see, e.g., src/main.c in the Coloring example).
4707  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mydisplaycolumn".
4708  * -# Adjust the \ref DISP_PROPERTIES "properties of the display column".
4709  * -# Define the \ref DISP_DATA "display column data". This is optional.
4710  * -# Implement the \ref DISP_INTERFACE "interface methods".
4711  * -# Implement the \ref DISP_FUNDAMENTALCALLBACKS "fundamental callback methods".
4712  * -# Implement the \ref DISP_ADDITIONALCALLBACKS "additional callback methods". This is optional.
4713  *
4714  *
4715  * @section DISP_PROPERTIES Properties of a Display Column
4716  *
4717  * At the top of the new file "disp_mydisplaycolumn.c" you can find the display column properties.
4718  * These are given as compiler defines.
4719  * In the C++ wrapper class, you have to provide the display column properties by calling the constructor
4720  * of the abstract base class scip::ObjDisp from within your constructor.
4721  * The properties you have to set have the following meaning:
4722  *
4723  * \par DISP_NAME: the name of the display column.
4724  * This name is used in the interactive shell to address the display column.
4725  * Additionally, if you are searching for a display column with SCIPfindDisp(), this name is looked up.
4726  * Names have to be unique: no two display columns may have the same name.
4727  *
4728  * \par DISP_DESC: the description of the display column.
4729  * This string is printed as a description of the display column in the interactive shell.
4730  *
4731  * \par DISP_HEADER: the header of the display column.
4732  * This string is printed as the header of the display column in the status information display.
4733  *
4734  * \par DISP_WIDTH: the width of the display column.
4735  * This parameter defines the width (number of characters) of the display column. The value of the parameter has to be
4736  * greater than or equal to the number of characters in the header string.
4737  *
4738  * \par DISP_PRIORITY: the priority of the display column.
4739  * The total width of status information lines is bounded by the parameter "display width". The display columns actually contained
4740  * in the status information display are selected in decreasing order of their priority. Furthermore, the user can force
4741  * columns to be displayed or not to be displayed in the status information display. For that, (s)he has to switch the value
4742  * of the display column's parameter "active" from "auto" (its default value) to "on" or "off", respectively.
4743  *
4744  * \par DISP_POSITION: the relative position of the display column.
4745  * In the status information display, the display columns are arranged from left to right in increasing order of their
4746  * relative position.
4747  *
4748  * \par DISP_STRIPLINE: the default for whether the display column should be separated with a line from its right neighbor.
4749  * This parameter states whether the display column should be separated with the string "|" from its right neighbor. In so
4750  * doing, the clearness of the status information display may improve.
4751  *
4752  * @section DISP_DATA Display Column Data
4753  *
4754  * Below the header "Data structures" you can find a struct which is called "struct SCIP_DispData".
4755  * In this data structure, you can store the data of your display column. For example, you should store the adjustable
4756  * parameters of the display column in this data structure.
4757  * If you are using C++, you can add display column data as usual as object variables to your class.
4758  * \n
4759  * Defining display column data is optional. You can leave the struct empty.
4760  *
4761  *
4762  * @section DISP_INTERFACE Interface Methods
4763  *
4764  * At the bottom of "disp_mydisplaycolumn.c" you can find the interface method SCIPincludeDispMydisplaycolumn(), which also
4765  * appears in "disp_mydisplaycolumn.h".
4766  * \n
4767  * This method only has to be adjusted slightly.
4768  * It is responsible for notifying SCIP of the presence of the display column by calling the method
4769  * SCIPincludeDisp().
4770  *
4771  * The interface method is called by the user, if (s)he wants to include the display column, i.e., if (s)he wants to use the display column in his
4772  * application.
4773  *
4774  * If you are using display column data, you have to allocate the memory for the data at this point.
4775  * You can do this by calling:
4776  * \code
4777  * SCIP_CALL( SCIPallocMemory(scip, &dispdata) );
4778  * \endcode
4779  * You also have to initialize the fields in struct SCIP_DispData afterwards.
4780  *
4781  * Although this is very uncommon, you may also add user parameters for your display column, see the method
4782  * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
4783  *
4784  *
4785  * @section DISP_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Display Column
4786  *
4787  * Display column plugins have only one fundamental callback method, namely the \ref DISPOUTPUT method.
4788  * This method has to be implemented for every display column; the other callback methods are optional.
4789  * In the C++ wrapper class scip::ObjDisp, the scip_output() method (which corresponds to the \ref DISPOUTPUT callback) is a virtual
4790  * abstract member function.
4791  * You have to implement it in order to be able to construct an object of your display column class.
4792  *
4793  * Additional documentation for the callback methods can be found in type_disp.h.
4794  *
4795  * @subsection DISPOUTPUT
4796  *
4797  * The DISPOUTPUT callback is called after each pricing loop during node processing and after a node has been processed.
4798  * In addition, at the root node, the callback is executed after each iteration of the price-and-cut loop.
4799  * It should write the display column information for the current node to a given output file stream.
4800  *
4801  * Typical methods called by a display column are, for example, SCIPdispLongint(), SCIPdispInt(), SCIPdispTime(), and
4802  * SCIPinfoMessage().
4803  *
4804  *
4805  * @section DISP_ADDITIONALCALLBACKS Additional Callback Methods of a Display Column
4806  *
4807  * The additional callback methods do not need to be implemented in every case.
4808  * They can be used, for example, to initialize and free private data.
4809  *
4810  * @subsection DISPCOPY
4811  *
4812  * The DISPCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this callback
4813  * as <code>NULL</code> the user disables the execution of the specified column. In general it is probably not needed to
4814  * implement that callback since the output of the copied instance is usually suppressed. In the other case or for
4815  * debugging the callback should be implement.
4816  *
4817  *
4818  * @subsection DISPFREE
4819  *
4820  * If you are using display column data, you have to implement this method in order to free the display column data.
4821  * This can be done by the following procedure:
4822  * \code
4823  * static
4824  * SCIP_DECL_DISPFREE(dispFreeMydisplaycolumn)
4825  * {
4826  * SCIP_DISPDATA* dispdata;
4827  *
4828  * dispdata = SCIPdispGetData(disp);
4829  * assert(dispdata != NULL);
4830  *
4831  * SCIPfreeMemory(scip, &dispdata);
4832  *
4833  * SCIPdispSetData(disp, NULL);
4834  *
4835  * return SCIP_OKAY;
4836  * }
4837  * \endcode
4838  * If you have allocated memory for fields in your display column data, remember to free this memory
4839  * before freeing the display column data itself.
4840  * If you are using the C++ wrapper class, this method is not available.
4841  * Instead, just use the destructor of your class to free the member variables of your class.
4842  *
4843  * @subsection DISPINIT
4844  *
4845  * The DISPINIT callback is executed after the problem is transformed.
4846  * The display column may, e.g., use this call to initialize its display column data.
4847  *
4848  * @subsection DISPEXIT
4849  *
4850  * The DISPEXIT callback is executed before the transformed problem is freed.
4851  * In this method, the display column should free all resources that have been allocated for the solving process in
4852  * \ref DISPINIT.
4853  *
4854  * @subsection DISPINITSOL
4855  *
4856  * The DISPINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
4857  * begin. The display column may use this call to initialize its branch-and-bound specific data.
4858  *
4859  * @subsection DISPEXITSOL
4860  *
4861  * The DISPEXITSOL callback is executed before the branch-and-bound process is freed. The display column should use this
4862  * call to clean up its branch-and-bound data specific data.
4863  */
4864 
4865 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
4866 /**@page EVENT How to add event handler
4867  *
4868  * While solving a constraint integer program, SCIP drops thousands of events such as SCIP_EVENTTYPE_VARFIXED (a
4869  * complete list of all events is given in type_event.h). These events can be caught and used to do something after a
4870  * certain event happens. Events can be used to speed up the solution process. For example, the set partitioning
4871  * constraint is only worth propagating if one of the involved variables is fixed. This can be detected by
4872  * catching the event SCIP_EVENTTYPE_VARFIXED. To be able to catch an event it is necessary to write an event handler
4873  * which defines what to do after a certain event was caught.
4874  *
4875  * We now explain how users can add their own event handlers. We give the explanation for creating your own
4876  * source file for each additional event handler. Of course, you can collect different event handlers in one source file
4877  * or you can put the event handler directly into the constraint handler. In a \ref EVENTUSAGE "second step" we discuss
4878  * the usage of an event handler. This means how to catch and drop events. \ref EVENTTYPES "Finally", we give some notes on the existing
4879  * types of events.
4880  *
4881  * Take src/scip/cons_logior.c, where the event handler is directly included into the constraint handler. As all other
4882  * default plugins, the event handlers are written in C. C++ users can easily adapt the code by using the scip::ObjEventhdlr
4883  * wrapper base class and implement the scip_...() virtual methods instead of the SCIP_DECL_EVENT... callback methods.
4884  *
4885  * Additional documentation for the callback methods of an event handler can be found in the file type_event.h. There is
4886  * also an example written in C which deals with an event handler. You find this example in the directory
4887  * "examples/Eventhdlr/". An C++ example can be found within the TSP project (examples/TSP/src/EventhdlrNewSol.cpp).
4888  *
4889  * Here is what you have to do to implement an event handler (assuming your event handler is named "bestsol"):
4890  * -# Copy the template files src/scip/event_xyz.c and src/scip/event_xyz.h into files named "event_bestsol.c"
4891  * and "event_bestsol.h".
4892  \n
4893  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
4894  * -# Use SCIPincludeEventBestsol() in order to include the event handler into your SCIP instance,
4895  * e.g., in the main file of your project (see, e.g., src/cmain.c in the Eventhdlr example).
4896  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "bestsol".
4897  * -# Adjust the \ref EVENTHDLR_PROPERTIES "properties of the event handler".
4898  * -# Implement the \ref EVENT_INTERFACE "interface methods".
4899  * -# Implement the \ref EVENT_FUNDAMENTALCALLBACKS "fundamental callback methods".
4900  * -# Implement the \ref EVENT_ADDITIONALCALLBACKS "additional callback methods". This is optional.
4901  *
4902  *
4903  * @section EVENTHDLR_PROPERTIES Properties of a Event Handler
4904  *
4905  * At the top of the new file "event_bestsol.c" you can find the event handler properties.
4906  * These are given as compiler defines.
4907  * In the C++ wrapper class, you have to provide the event handler properties by calling the constructor
4908  * of the abstract base class scip::ObjEventhdlr from within your constructor.
4909  * The properties you have to set have the following meaning:
4910  *
4911  * \par EVENT_NAME: the name of the event handler.
4912  * This name has to be unique with respect to all other event handlers. If you are searching for an event handler with
4913  * SCIPfindEventhdlr(), this name is looked up.
4914  *
4915  * \par EVENT_DESC: the description of the event handler.
4916  * This string is printed as a description of the event handler.
4917  *
4918  * @section EVENTHDLR_DATA Event Handler Data
4919  *
4920  * Below the header "Data structures" you can find a struct which is called "struct SCIP_EventhdlrData".
4921  * In this data structure, you can store the data of your event handler. For example, you should store the adjustable
4922  * parameters of the event handler in this data structure.
4923  * If you are using C++, you can add event handler data as usual as object variables to your class.
4924  * \n
4925  * Defining event handler data is optional. You can leave the struct empty.
4926  *
4927  *
4928  * @section EVENT_INTERFACE Interface Methods
4929  *
4930  * At the bottom of "event_bestsol.c", you can find the interface method SCIPincludeEventBestsol(),
4931  * which also appears in "event_bestsol.h".
4932  * SCIPincludeEventBestsol() is called by the user, if (s)he wants to include the event handler,
4933  * i.e., if (s)he wants to use the event handler in his/her application.
4934  *
4935  * This method only has to be adjusted slightly.
4936  * It is responsible for notifying SCIP of the presence of the event handler. For this, you can either call
4937  * SCIPincludeEventhdlr(),
4938  * or SCIPincludeEventhdlrBasic() since SCIP version 3.0. In the latter variant, \ref EVENT_ADDITIONALCALLBACKS "additional callbacks"
4939  * must be added via setter functions as, e.g., SCIPsetReaderCopy(). We recommend this latter variant because
4940  * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first
4941  * variant must be manually adjusted with every SCIP release containing new callbacks for event handlers in order to compile.
4942  *
4943  * If you are using event handler data, you have to allocate the memory for the data at this point.
4944  * You can do this by calling:
4945  * \code
4946  * SCIP_CALL( SCIPallocMemory(scip, &eventhdlrdata) );
4947  * \endcode
4948  * You also have to initialize the fields in struct SCIP_EventhdlrData afterwards.
4949  *
4950  * Although this is very uncommon, you may also add user parameters for your event handler, see the method
4951  * SCIPincludeConshdlrKnapsack() in the \ref cons_knapsack.h "knapsack constraint handler" for an example.
4952  *
4953  *
4954  * @section EVENT_FUNDAMENTALCALLBACKS Fundamental Callback Methods of a Event Handler
4955  *
4956  * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
4957  * an operational algorithm.
4958  * They are passed together with the event handler itself to SCIP using SCIPincludeEventhdlr() or SCIPincludeEventhdlrBasic(),
4959  * see @ref EVENT_INTERFACE.
4960  *
4961  *
4962  * Event handler plugins have only one fundamental callback method, namely the \ref EVENTEXEC method. This method has
4963  * to be implemented for every event handler; the other callback methods are optional. In the C++ wrapper class
4964  * scip::ObjEventhdlr, the scip_exec() method (which corresponds to the \ref EVENTEXEC callback) is a virtual abstract member
4965  * function. You have to implement it in order to be able to construct an object of your event handler class.
4966  *
4967  * Additional documentation for the callback methods can be found in type_event.h.
4968  *
4969  * @subsection EVENTEXEC
4970  *
4971  * The EVENTEXEC callback is called after the requested event happened. Then the event handler can do some action in
4972  * reaction to the event.
4973  *
4974  * Typical the execution method sets a parameter to TRUE to indicate later in solving process that something happened
4975  * which should be analyzed further. In the \ref cons_knapsack.h "knapsack constraint handler" you find such a typical
4976  * example.
4977  *
4978  * @section EVENT_ADDITIONALCALLBACKS Additional Callback Methods of a Event Handler
4979  *
4980  * The additional callback methods do not need to be implemented in every case. However, some of them have to be
4981  * implemented for most applications, they can be used, for example, to initialize and free private data.
4982  * Additional callbacks can either be passed directly with SCIPincludeEventhdlr() to SCIP or via specific
4983  * <b>setter functions</b> after a call of SCIPincludeEventhdlrBasic(), see also @ref EVENT_INTERFACE.
4984  *
4985  * @subsection EVENTCOPY
4986  *
4987  * The EVENTCOPY callback is executed when a SCIP instance is copied, e.g. to solve a sub-SCIP. By defining this
4988  * callback as <code>NULL</code> the user disables the execution of the specified event handler for all copied SCIP
4989  * instances. Note that in most cases the event handler in the copied instance will be initialize by those objects (such
4990  * as constraint handlers or propagators) which need this event handler (see \ref cons_knapsack.h). In these cases the copy
4991  * callback can be ignored. In case of general events, such as a new best solution being found
4992  * (SCIP_EVENTTYPE_BESTSOLFOUND), you might want to implement that callback. The event handler example which you find
4993  * in the directory "examples/Eventhdlr/" uses that callback.
4994  *
4995  * \code
4996  * static
4997  * SCIP_DECL_EVENTCOPY(eventCopyBestsol)
4998  * {
4999  * assert(scip != NULL);
5000  * assert(eventhdlr != NULL);
5001  * assert(strcmp(SCIPeventhdlrGetName(eventhdlr), EVENTHDLR_NAME) == 0);
5002  *
5003  * SCIP_CALL( SCIPincludeEventHdlrBestsol(scip) );
5004  *
5005  * return SCIP_OKAY;
5006  * }
5007  * \endcode
5008  *
5009  *
5010  * @subsection EVENTFREE
5011  *
5012  * If you are using event handler data, you have to implement this method in order to free the event handler data.
5013  * This can be done by the following procedure:
5014  * \code
5015  * static
5016  * SCIP_DECL_EVENTFREE(eventFreeBestsol)
5017  * {
5018  * SCIP_EVENTHDLRDATA* eventhdlrdata;
5019  *
5020  * eventhdlrdata = SCIPeventhdlrGetData(eventhdlr);
5021  * assert(eventhdlrdata != NULL);
5022  *
5023  * SCIPfreeMemory(scip, &eventhdlrdata);
5024  *
5025  * SCIPeventhdlrSetData(eventhdlr, NULL);
5026  *
5027  * return SCIP_OKAY;
5028  * }
5029  * \endcode
5030  * If you have allocated memory for fields in your event handler data, remember to free this memory
5031  * before freeing the event handler data itself.
5032  * If you are using the C++ wrapper class, this method is not available.
5033  * Instead, just use the destructor of your class to free the member variables of your class.
5034  *
5035  *
5036  * @subsection EVENTINIT
5037  *
5038  * The EVENTINIT callback is executed after the problem is transformed.
5039  * The event handler may, e.g., use this call to initialize its event handler data.
5040  *
5041  * @subsection EVENTEXIT
5042  *
5043  * The EVENTEXIT callback is executed before the transformed problem is freed.
5044  * In this method, the event handler should free all resources that have been allocated for the solving process in
5045  * \ref EVENTINIT.
5046  *
5047  * @subsection EVENTINITSOL
5048  *
5049  * The EVENTINITSOL callback is executed when the presolving is finished and the branch-and-bound process is about to
5050  * begin. The event handler may use this call to initialize its branch-and-bound specific data.
5051  *
5052  * @subsection EVENTEXITSOL
5053  *
5054  * The EVENTEXITSOL callback is executed before the branch-and-bound process is freed. The event handler should use this
5055  * call to clean up its branch-and-bound data specific data.
5056  *
5057  * @section EVENTUSAGE Catching and Dropping Events
5058  *
5059  * After you have implemented the event handler, you have to tell SCIP for which events this event handler should be
5060  * used. This can be a general events, such as <code>SCIP_EVENTTYPE_BESTSOLFOUND</code>, or a variable event which is the most common
5061  * way.
5062  *
5063  * In case of a general (not variable) event you use the function SCIPcatchEvent() to attach to an event and
5064  * SCIPdropEvent() to release this event later.
5065  *
5066  * \code
5067  * SCIP_CALL( SCIPcatchEvent( scip, SCIP_EVENTTYPE_BESTSOLFOUND, eventhdlr, NULL, NULL) );
5068  * \endcode
5069  *
5070  * \code
5071  * SCIP_CALL( SCIPdropEvent( scip, SCIP_EVENTTYPE_BESTSOLFOUND, eventhdlr, NULL, NULL) );
5072  * \endcode
5073  *
5074  * If you want trigger some variable event, you use the method SCIPcatchVarEvent() to attach the variable event and
5075  * SCIPdropVarEvent() to drop it later.
5076  *
5077  * \code
5078  * SCIP_CALL( SCIPcatchVarEvent( scip, var, SCIP_EVENTTYPE_VARFIXED, eventhdlr, NULL, NULL) );
5079  * \endcode
5080  *
5081  * \code
5082  * SCIP_CALL( SCIPdropVarEvent( scip, var, SCIP_EVENTTYPE_VARFIXED, eventhdlr, NULL, NULL) );
5083  * \endcode
5084  *
5085  * @section EVENTTYPES Event types
5086  *
5087  * All available events are listed in type_event.h. There are atomic events such as <code>SCIP_EVENTTYPE_VARFIXED</code>
5088  * and combined events such as <code>SCIP_EVENTTYPE_VARCHANGED</code>. The events are encoded via bit masks. Each atomic
5089  * event has a unique power of two. This enables combination of the atomic events.
5090  *
5091  * SCIP only throws atomic events. However, an event handler might be interested in bunch of events. Through the
5092  * underlying bit masks it is possible to combine the atomic events. For example, <code>SCIP_EVENTTYPE_VARCHANGED</code>
5093  * is an event which combines the events <code>SCIP_EVENTTYPE_VARFIXED</code>, <code>SCIP_EVENTTYPE_VARUNLOCKED</code>,
5094  * <code>SCIP_EVENTTYPE_OBJCHANGED</code>, <code>SCIP_EVENTTYPE_GBDCHANGED</code>,
5095  * <code>SCIP_EVENTTYPE_DOMCHANGED</code>, and <code>SCIP_EVENTTYPE_IMPLADDED</code>.
5096  *
5097  * \code
5098  * #define SCIP_EVENTTYPE_VARCHANGED (SCIP_EVENTTYPE_VARFIXED | SCIP_EVENTTYPE_VARUNLOCKED | SCIP_EVENTTYPE_OBJCHANGED
5099  * | SCIP_EVENTTYPE_GBDCHANGED | SCIP_EVENTTYPE_DOMCHANGED | SCIP_EVENTTYPE_IMPLADDED)
5100  * \endcode
5101  *
5102  * Depending on the event type, the event offers different information. The methods which can be used to gain
5103  * access to this information are given in pub_event.h.
5104  *
5105  */
5106 
5107 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5108 /**@page NLPI How to add interfaces to nonlinear programming solvers
5109  *
5110  * NLPIs are used to interface a solver for nonlinear programs (NLP).
5111  * It is used, e.g., to solve convex relaxations of the problem or to find locally optimal solutions of
5112  * nonlinear relaxations or subproblems.
5113  * The NLPI has been designed such that it can be used independently from SCIP.
5114  *
5115  * While the NLPI itself corresponds to the solver interface, the NLPIPROBLEM corresponds to the
5116  * (solver specific) representation of a concrete nonlinear program.
5117  * An NLP is specified as a set of indexed variables with variable bounds, an objective function,
5118  * and a set of constraints, where each constraint is specified as a function which is restricted to lie
5119  * between given left and right hand sides (possibly infinite).
5120  * A function consists of a linear, quadratic, and general nonlinear part.
5121  * The linear and quadratic parts are specified via variable indices and coefficients, while the
5122  * general nonlinear part is specified via an expression tree.
5123  * That is, the user of the NLPI does not provide function evaluation callbacks but an algebraic representation of the NLP.
5124  * Interfaces for solvers that require function evaluations can make use of the NLPIORACLE, which
5125  * provides a set of methods to compute functions values, gradients, Jacobians, and Hessians for a given NLP.
5126  * See the interface to Ipopt for an example on how to use the NLPIORACLE.
5127  *
5128  * A complete list of all NLPIs contained in this release can be found \ref NLPIS "here".
5129  *
5130  * We now explain how users can add their own NLP solver interface.
5131  * Take the interface to Ipopt (src/nlpi/nlpi_ipopt.cpp) as an example.
5132  * Unlike most other plugins, it is written in C++.
5133  * Additional documentation for the callback methods of an NLPI, in particular for their input parameters,
5134  * can be found in the file type_nlpi.h.
5135  *
5136  * Here is what you have to do to implement an NLPI:
5137  * -# Copy the template files src/nlpi/nlpi_xyz.c and src/nlpi/nlpi_xyz.h into files named "nlpi_mynlpi.c"
5138  * and "nlpi_mynlpi.h".
5139  * \n
5140  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
5141  * -# Use SCIPcreateNlpSolverMynlpi() in order to include the NLPI into your SCIP instance,
5142  * e.g., in the main file of your project (see, e.g., src/main.c in the Coloring example).
5143  * -# Open the new files with a text editor and replace all occurrences of "xyz" by "mynlpi".
5144  * -# Adjust the properties of the nlpi (see \ref NLPI_PROPERTIES).
5145  * -# Define the NLPI and NLPIPROBLEM data (see \ref NLPI_DATA).
5146  * -# Implement the interface methods (see \ref NLPI_INTERFACE).
5147  * -# Implement the fundamental callback methods (see \ref NLPI_FUNDAMENTALCALLBACKS).
5148  *
5149  *
5150  * @section NLPI_PROPERTIES Properties of an NLPI
5151  *
5152  * At the top of the new file "nlpi_mynlpi.c", you can find the NLPI properties.
5153  * These are given as compiler defines.
5154  * The properties you have to set have the following meaning:
5155  *
5156  * \par NLPI_NAME: the name of the NLP solver interface.
5157  * This name is used in the interactive shell to address the NLPI.
5158  * Additionally, if you are searching for an NLPI with SCIPfindNLPI(), this name is looked up.
5159  * Names have to be unique: no two NLPIs may have the same name.
5160  *
5161  * \par NLPI_DESC: the description of the NLPI.
5162  * This string is printed as a description of the NLPI in the interactive shell.
5163  *
5164  * \par NLPI_PRIORITY: the priority of the NLPI.
5165  * If an NLP has to be solved, an NLP solver has to be selected.
5166  * By default, the solver with the NLPI with highest priority is selected.
5167  * The priority of an NLPI should be set according to performance of the solver:
5168  * solvers that provide fast algorithms that are usually successful on a wide range of problems should have a high priority.
5169  * An easy way to list the priorities of all NLPIs is to type "display nlpis" in the interactive shell of SCIP.
5170  *
5171  * @section NLPI_DATA NLPI Data
5172  *
5173  * Below the header "Data structures" you can find structs which are called "struct SCIP_NlpiData" and "struct SCIP_NlpiProblem".
5174  * In this data structure, you can store the data of your solver interface and of a specific NLP problem.
5175  * For example, you could store a pointer to the block memory data structure in the SCIP_NlpiData data structure
5176  * and store a pointer to an NLPIoracle in the SCIP_NlpiProblem data structure.
5177  *
5178  * @section NLPI_INTERFACE Interface Methods
5179  *
5180  * At the bottom of "nlpi_mynlpi.c", you can find the interface method SCIPcreateNlpSolverXyz(),
5181  * which also appears in "nlpi_mynlpi.h".
5182  * \n
5183  * This method only has to be adjusted slightly.
5184  * It is responsible for creating an NLPI that contains all properties and callback methods of your
5185  * solver interface by calling the method SCIPnlpiCreate().
5186  * SCIPcreateNlpSolverXyz() is called by the user (e.g., SCIP), if (s)he wants to use this solver interface in his/her application.
5187  *
5188  * If you are using NLPI data, you have to allocate the memory for the data at this point.
5189  * You can do this by calling:
5190  * \code
5191  * SCIP_CALL( SCIPallocMemory(scip, &nlpidata) );
5192  * \endcode
5193  * You also have to initialize the fields in struct SCIP_NlpiData afterwards. For freeing the
5194  * NLPI data, see \ref NLPIFREE.
5195  *
5196  *
5197  * @section NLPI_FUNDAMENTALCALLBACKS Fundamental Callback Methods of an NLPI
5198  *
5199  * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain
5200  * an operational algorithm. Currently, all NLPI callbacks are fundamental.
5201  *
5202  * Additional documentation of the callback methods, in particular to their input parameters,
5203  * can be found in type_nlpi.h.
5204  *
5205  * @subsection NLPICOPY
5206  *
5207  * The NLPICOPY callback is executed if the plugin should be copied, e.g., when a SCIP instance is copied.
5208  *
5209  * @subsection NLPIFREE
5210  *
5211  * The NLPIFREE callback is executed if the NLP solver interface data structure should be freed, e.g., when a SCIP instance is freed.
5212  *
5213  * @subsection NLPIGETSOLVERPOINTER
5214  *
5215  * The NLPIGETSOLVERPOINTER callback can be used to pass a pointer to a solver specific data structure to the user.
5216  *
5217  * @subsection NLPICREATEPROBLEM
5218  *
5219  * The NLPICREATEPROBLEM callback is executed if a particular NLP problem is to be created.
5220  * The callback method should initialize a SCIP_NlpiProblem struct here that corresponds to an empty NLP.
5221  *
5222  * @subsection NLPIFREEPROBLEM
5223  *
5224  * The NLPIFREEPROBLEMPOINTER callback is executed if a particular NLP problem is to be freed.
5225  * The callback method should free a SCIP_NlpiProblem struct here.
5226  *
5227  * @subsection NLPIGETPROBLEMPOINTER
5228  *
5229  * The NLPIGETPROBLEMPOINTER callback can be used to pass a pointer to a solver specific data structure of the NLP to the user.
5230  *
5231  * @subsection NLPIADDVARS
5232  *
5233  * The NLPIADDVARS callback is executed if a set of variables with lower and upper bounds and names should be added to a particular NLP.
5234  * The callback method must add the new variables behind the previously added variables, if any.
5235  * If NULL is given for the lower bounds arguments, -infinity is assumed as lower bound for each new variable.
5236  * If NULL is given for the upper bounds arguments, +infinity is assumed as upper bound for each new variable.
5237  * It is also permitted to use NULL for the names argument.
5238  *
5239  * @subsection NLPIADDCONSTRAINTS
5240  *
5241  * The NLPIADDCONSTRAINTS callback is executed if a set of constraints should be added to a particular NLP.
5242  * Constraints are specified by providing left and right hand sides, linear and quadratic coefficients, expression trees, and constraint names.
5243  * All of these arguments are optional, giving NULL for left hand sides corresponds to -infinity, giving NULL for right hand sides corresponds to +infinity.
5244  *
5245  * @subsection NLPISETOBJECTIVE
5246  *
5247  * The NLPISETOBJECTIVE callback is executed to set the objective function of a particular NLP.
5248  *
5249  * @subsection NLPICHGVARBOUNDS
5250  *
5251  * The NLPICHGVARBOUNDS callback is executed to change the bounds on a set of variables of an NLP.
5252  *
5253  * @subsection NLPICHGCONSSIDES
5254  *
5255  * The NLPICHGCONSSIDES callback is executed to change the sides on a set of constraints of an NLP.
5256  *
5257  * @subsection NLPIDELVARSET
5258  *
5259  * The NLPIDELVARSET callback is executed to delete a set of variables from an NLP.
5260  * The caller provides an array in which for each variable it is marked whether it should be deleted.
5261  * In the same array, the method should return the new position of each variable in the NLP, or -1 if it was deleted.
5262  *
5263  * @subsection NLPIDELCONSSET
5264  *
5265  * The NLPIDELCONSSET callback is executed to delete a set of constraints from an NLP.
5266  * The caller provides an array in which for each constraint it is marked whether it should be deleted.
5267  * In the same array, the method should return the new position of each constraint in the NLP, or -1 if it was deleted.
5268  *
5269  * @subsection NLPICHGLINEARCOEFS
5270  *
5271  * The NLPICHGLINEARCOEFS callback is executed to change the coefficients in the linear part of the objective function or a constraint of an NLP.
5272  *
5273  * @subsection NLPICHGQUADCOEFS
5274  *
5275  * The NLPICHGQUADCOEFS callback is executed to change the coefficients in the quadratic part of the objective function or a constraint of an NLP.
5276  *
5277  * @subsection NLPICHGEXPRTREE
5278  *
5279  * The NLPICHGEXPRTREE callback is executed to replace the expression tree of the objective function or a constraint of an NLP.
5280  *
5281  * @subsection NLPICHGNONLINCOEF
5282  *
5283  * The NLPICHGNONLINCOEF callback is executed to change a single parameter in the (parametrized) expression tree of the objective function or a constraint of an NLP.
5284  *
5285  * @subsection NLPICHGOBJCONSTANT
5286  *
5287  * The NLPICHGOBJCONSTANT callback is executed to change the constant offset of the objective function of an NLP.
5288  *
5289  * @subsection NLPISETINITIALGUESS
5290  *
5291  * The NLPISETINITIALGUESS callback is executed to provide primal and dual initial values for the variables and constraints of an NLP.
5292  * For a local solver, these values can be used as a starting point for the search.
5293  * 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).
5294  * In this case, the solver should clear previously set starting values and setup its own starting point.
5295  *
5296  * @subsection NLPISOLVE
5297  *
5298  * The NLPISOLVE callback is executed when an NLP should be solved.
5299  * The solver may use the initial guess provided by \ref NLPISETINITIALGUESS as starting point.
5300  * The status of the solving process and solution can be requested by
5301  * \ref NLPIGETSOLSTAT, \ref NLPIGETTERMSTAT, \ref NLPIGETSOLUTION, and \ref NLPIGETSTATISTICS.
5302  *
5303  * @subsection NLPIGETSOLSTAT
5304  *
5305  * The NLPIGETSOLSTAT callback can be used to request the solution status (solved, infeasible, ...) after an NLP has been solved.
5306  *
5307  * @subsection NLPIGETTERMSTAT
5308  *
5309  * The NLPIGETTERMSTAT callback can be used to request the termination reason (normal, iteration limit, ...) after an NLP has been solved.
5310  *
5311  * @subsection NLPIGETSOLUTION
5312  *
5313  * The NLPIGETSOLUTION callback can be used to request the primal and dual solution values after an NLP solve.
5314  * The method should pass pointers to arrays of variable values to the caller.
5315  * 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.
5316  *
5317  * @subsection NLPIGETSTATISTICS
5318  *
5319  * The NLPIGETSTATISTICS callback can be used to request the statistical values (number of iterations, time, ...) after an NLP solve.
5320  * The method should fill the provided NLPSTATISTICS data structure.
5321  *
5322  * <!-- NLPIGETWARMSTARTSIZE, NLPIGETWARMSTARTMEMO, NLPISETWARMSTARTMEMO are not documented,
5323  since they are currently not used, not implemented, and likely to change with a next version. -->
5324  *
5325  * @subsection NLPIGETINTPAR
5326  *
5327  * The NLPIGETINTPAR callback can be used to request the value of an integer valued NLP parameter.
5328  *
5329  * @subsection NLPISETINTPAR
5330  *
5331  * The NLPISETINTPAR callback is executed to set the value of an integer valued NLP parameter.
5332  *
5333  * @subsection NLPIGETREALPAR
5334  *
5335  * The NLPIGETREALPAR callback can be used to request the value of a real valued NLP parameter.
5336  *
5337  * @subsection NLPISETREALPAR
5338  *
5339  * The NLPISETREALPAR callback is executed to set the value of a real valued NLP parameter.
5340  *
5341  * @subsection NLPIGETSTRINGPAR
5342  *
5343  * The NLPIGETSTRINGPAR callback can be used to request the value of a string valued NLP parameter.
5344  *
5345  * @subsection NLPISETSTRINGPAR
5346  *
5347  * The NLPISETSTRINGPAR callback is executed to set the value of a string valued NLP parameter.
5348  */
5349 
5350 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5351 /**@page EXPRINT How to add interfaces to expression interpreters
5352  *
5353  * An expression interpreter is a tool to compute point-wise and interval-wise the function values, gradients, and
5354  * derivatives of algebraic expressions which are given in the form of an expression tree.
5355  * It is used, e.g., by an NLP solver interface to compute Jacobians and Hessians for the solver.
5356  *
5357  * The expression interpreter interface in SCIP has been implemented similar to those of the LP solver interface (LPI).
5358  * For one binary, exactly one expression interpreter has to be linked.
5359  * The expression interpreter API has been designed such that it can be used independently from SCIP.
5360  *
5361  * A complete list of all expression interpreters contained in this release can be found \ref EXPRINTS "here".
5362  *
5363  * We now explain how users can add their own expression interpreters.
5364  * Take the interface to CppAD (\ref exprinterpret_cppad.cpp) as an example.
5365  * Unlike most other plugins, it is written in C++.
5366  *
5367  * Additional documentation for the callback methods of an expression interpreter, in particular for their input parameters,
5368  * can be found in the file \ref exprinterpret.h
5369  *
5370  * Note that the expression interpreter API has <b>BETA status</b> and thus may change in the next version.
5371  *
5372  * Here is what you have to do to implement an expression interpreter:
5373  * -# Copy the file \ref exprinterpret_none.c into a file named "exprinterpreti_myexprinterpret.c".
5374  * \n
5375  * Make sure to adjust your Makefile such that these files are compiled and linked to your project.
5376  * -# Open the new files with a text editor.
5377  * -# Define the expression interpreter data (see \ref EXPRINT_DATA).
5378  * -# Implement the interface methods (see \ref EXPRINT_INTERFACE).
5379  *
5380  *
5381  * @section EXPRINT_DATA Expression Interpreter Data
5382  *
5383  * In "struct SCIP_ExprInt", you can store the general data of your expression interpreter.
5384  * For example, you could store a pointer to the block memory data structure.
5385  *
5386  * @section EXPRINT_INTERFACE Interface Methods
5387  *
5388  * The expression interpreter has to implement a set of interface method.
5389  * In your "exprinterpret_myexprinterpret.c", these methods are mostly dummy methods that return error codes.
5390  *
5391  * @subsection SCIPexprintGetName
5392  *
5393  * The SCIPexprintGetName method should return the name of the expression interpreter.
5394  *
5395  * @subsection SCIPexprintGetDesc
5396  *
5397  * The SCIPexprintGetDesc method should return a short description of the expression interpreter, e.g., the name of the developer of the code.
5398  *
5399  * @subsection SCIPexprintGetCapability
5400  *
5401  * The SCIPexprintGetCapability method should return a bitmask that indicates the capabilities of the expression interpreter,
5402  * i.e., whether it can evaluate gradients, Hessians, or do interval arithmetic.
5403  *
5404  * @subsection SCIPexprintCreate
5405  *
5406  * The SCIPexprintCreate method is called to create an expression interpreter data structure.
5407  * The method should initialize a "struct SCIP_ExprInt" here.
5408  *
5409  * @subsection SCIPexprintFree
5410  *
5411  * The SCIPexprintFree method is called to free an expression interpreter data structure.
5412  * The method should free a "struct SCIP_ExprInt" here.
5413  *
5414  * @subsection SCIPexprintCompile
5415  *
5416  * The SCIPexprintCompile method is called to initialize the data structures that are required to evaluate
5417  * a particular expression tree.
5418  * The expression interpreter can store data that is particular to a given expression tree in the tree by using
5419  * SCIPexprtreeSetInterpreterData().
5420  *
5421  * @subsection SCIPexprintFreeData
5422  *
5423  * The SCIPexprintFreeData method is called when an expression tree is freed.
5424  * The expression interpreter should free the given data structure.
5425  *
5426  * @subsection SCIPexprintNewParametrization
5427  *
5428  * The SCIPexprintNewParametrization method is called when the values of the parameters in a parametrized expression tree have changed.
5429  *
5430  * @subsection SCIPexprintEval
5431  *
5432  * The SCIPexprintEval method is called when the value of an expression represented by an expression tree should be computed for a point.
5433  *
5434  * @subsection SCIPexprintEvalInt
5435  *
5436  * The SCIPexprintEvalInt method is called when an interval that contains the range of an expression represented by an expression tree with respect to intervals for the variables should be computed.
5437  *
5438  * @subsection SCIPexprintGrad
5439  *
5440  * The SCIPexprintGrad method is called when the gradient of an expression represented by an expression tree should be computed for a point.
5441  *
5442  * @subsection SCIPexprintGradInt
5443  *
5444  * The SCIPexprintGradInt method is called when an interval vector that contains the range of the gradients of an expression represented by an expression tree with respect to intervals for the variables should be computed.
5445  *
5446  * @subsection SCIPexprintHessianSparsityDense
5447  *
5448  * The SCIPexprintHessianSparsityDense method is called when the sparsity structure of the Hessian matrix should be computed and returned in dense form.
5449  *
5450  * @subsection SCIPexprintHessianDense
5451  *
5452  * The SCIPexprintHessianDense method is called when the Hessian of an expression represented by an expression tree should be computed for a point.
5453  */
5454 
5455 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5456 /**@page CONF How to use conflict analysis
5457  *
5458  * Conflict analysis is a way to automatically use the information obtained from infeasible nodes
5459  * in the branch-and-bound tree.
5460  *
5461  * Once a node is declared infeasible, SCIP automatically tries to infer a constraint that explains the reason for the
5462  * infeasibility, in order to avoid similar situations later in the search. This explanation essentially consists of a
5463  * constraint stating that at least one of its variables should have a bound different from the current infeasible node,
5464  * because the current setting led to infeasibility. Clearly, all variables that are fixed in the current infeasible
5465  * node would yield such a constraint (since this leads to infeasibility). The key point rather is to infer a "small"
5466  * constraint that does the same job. SCIP handles this by several heuristics. For this, SCIP sets up a
5467  * so-called (directed) conflict graph. The nodes in this graph correspond to bound changes of variables and an arc (@a
5468  * u, @a v) means that the bound change corresponding to @a v is based on the bound change of @a u. In general, a node
5469  * will have several ingoing arcs which represent all bound changes that have been used to infer (propagate) the bound
5470  * change in question. The graph also contains source nodes for each bound that has been changed during branching and an
5471  * artificial target node representing the conflict, i.e., the infeasibility. Essentially, SCIP heuristically constructs
5472  * a cut in this graph that involves few "branching nodes". For details on the techniques that SCIP uses,
5473  * we refer to the paper @par
5474  * Tobias Achterberg, Conflict Analysis in Mixed Integer Programming@n
5475  * Discrete Optimization, 4, 4-20 (2007)
5476  *
5477  * For conflict analysis to work well, the author of a \ref CONS "Constraint Handler" or a
5478  * \ref PROP "Propagator" has to implement three kinds of functionality:
5479  *
5480  * -# If one detects infeasibility, one should initiate conflict analysis, see \ref INITCONFS "below".
5481  * -# During propagation, one should call the right functions to fix variables.
5482  * -# One should implement the <em>so-called reverse propagation</em>.
5483  *
5484  * If this functionality is not implemented, SCIP will still work correctly, but cannot use the information of the constraint
5485  * handler or the propagator for conflict analysis. In this case, each bound reduction performed by the constraint
5486  * handler/propagator will be treated as if it had been a branching decision.
5487  *
5488  * @section INITCONFS Initiating Conflict Analysis
5489  *
5490  * If one detects infeasibility within propagation, one should do the following:
5491  * -# Call SCIPinitConflictAnalysis().
5492  * -# Inform SCIP about the variable bounds that are the reason for the detection of infeasibility
5493  * via the functions SCIPaddConflictLb(), SCIPaddConflictUb(), SCIPaddConflictBd(), or
5494  * SCIPaddConflictBinvar(). If there is more than one valid explanation of infeasibility, either one can be used.
5495  * Typically, smaller explanations tend to be better.
5496  * -# Call SCIPanalyzeConflict() from a propagator or SCIPanalyzeConflictCons() from a constraint
5497  * handler.
5498  *
5499  * This functionality allows SCIP to set up the conflict graph and perform a conflict analysis.
5500  *
5501  * @section Propagation
5502  *
5503  * When propagating variable domains, SCIP needs to be informed that the deduced variable bounds should be
5504  * used in conflict analysis. This can be done by the functions SCIPinferVarLbCons(),
5505  * SCIPinferVarUbCons(), and SCIPinferBinvarCons() for constraint handlers and SCIPinferVarLbProp(),
5506  * SCIPinferVarUbProp(), and SCIPinferBinvarProp() for propagators. You can pass one integer of
5507  * information that should indicate the reason of the propagation and can be used in reverse
5508  * propagation, see the next section.
5509  *
5510  * @section RESPROP Reverse Propagation
5511  *
5512  * Reverse Propagation is used to build up the conflict graph. Essentially, it provides an algorithm to detect the arcs
5513  * leading to a node in the conflict graph, i.e., the bound changes responsible for the new bound change deduced during
5514  * propagation. Reverse Propagation needs to be implemented in the RESPROP callback functions of
5515  * \ref CONSRESPROP "constraint handlers" or \ref PROPRESPROP "propagators".
5516  * These callbacks receive the following information: the variable which is under investigation (@p
5517  * infervar), the corresponding bound change (@p bdchgidx, @p boundtype), and the integer (@p inferinfo) that has been
5518  * supplied during propagation.
5519  *
5520  * One can use SCIPvarGetUbAtIndex() or SCIPvarGetLbAtIndex() to detect the bounds before or after the propagation that
5521  * should be investigated. Then the bounds that were involved should be passed to SCIP via SCIPaddConflictLb() and
5522  * SCIPaddConflictUb(). If there is more than one valid explanation of infeasibility, either one can be used.
5523  * Typically, smaller explanations tend to be better.
5524  *
5525  * Details and (more) examples are given in Sections @ref CONSRESPROP and @ref PROPRESPROP.
5526  *
5527  *
5528  * @section Example
5529  *
5530  * Consider the constraint handler @p cons_linearordering.c in the
5531  * <a href="http://scip.zib.de/doc/examples/LOP"><b>linear ordering example</b></a>
5532  * (see @p example/LOP directory). This constraint handler propagates the equations \f$x_{ij} + x_{ji} =
5533  * 1\f$ and triangle inequalities \f$x_{ij} + x_{jk} + x_{ki} \leq 2\f$.
5534  *
5535  * When propagating the equation and <code>vars[i][j]</code> is fixed to 1, the constraint handler uses
5536  * \code
5537  * SCIP_CALL( SCIPinferBinvarCons(scip, vars[j][i], FALSE, cons, i*n + j, &infeasible, &tightened) );
5538  * \endcode
5539  * Thus, variable <code>vars[j][i]</code> is fixed to 0 (@p FALSE), and it passes <code>i*n + j </code> as @p inferinfo.
5540  *
5541  * When it propagates the triangle inequality and both <code>vars[i][j]</code> and <code>vars[j][k]</code>
5542  * are fixed to 1, the constraint handler uses
5543  * \code
5544  * SCIP_CALL( SCIPinferBinvarCons(scip, vars[k][i], FALSE, cons, n*n + i*n*n + j*n + k, &infeasible, &tightened) );
5545  * \endcode
5546  * Thus, in this case, variable <code>vars[k][i]</code> is fixed to 0 and <code>n*n + i*n*n + j*n + k</code> is
5547  * passed as <code>inferinfo</code>.
5548  *
5549  * In reverse propagation, the two cases can be distinguished by @p inferinfo: if it is less than @p n*n,
5550  * we deal with an equation, otherwise with a triangle inequality. The constraint handler can then extract the
5551  * indices @p i, @p j (and @p k in the second case) from inferinfo.
5552  *
5553  * In the first case, it has to distinguish whether <code>vars[i][j]</code> is fixed to 0 or 1 &ndash;
5554  * by calling SCIPaddConflictLb()
5555  * or SCIPaddConflictUb(), respectively, with variable <code>vars[j][i]</code>. In the second case, it is clear that the only
5556  * possible propagation is to fix <code>vars[i][j]</code> to 0 when both <code>vars[k][i]</code> and <code>vars[j][k]</code>
5557  * are fixed to 1. It then calls
5558  * SCIPaddConflictLb() for both <code>vars[k][i]</code> and <code>vars[j][k]</code>.
5559  */
5560 
5561 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5562 /**@page OBJ Creating, capturing, releasing, and adding data objects
5563  *
5564  * Data objects (variables, constraints, rows, ... ) are subject to reference counting
5565  * to avoid expensive copying operations. This concept is similar to smart pointers.
5566  * Creating such an object (e.g., by calling SCIPcreateVar()) will set the
5567  * reference counter to one. Capturing an object (e.g., by calling SCIPcaptureVar()) increases the reference counter,
5568  * releasing it (e.g., by calling SCIPreleaseVar()) decreases the counter. If the reference counter gets zero, the
5569  * object will be destroyed automatically.
5570  *
5571  * Remember that a created data object is automatically captured. If the user
5572  * doesn't need the object anymore, (s)he has to call the object's release method.
5573  *
5574  * When a data object is added to SCIP (e.g., by calling SCIPaddVar()) , it is captured again, such that a
5575  * release call does not destroy the object. If SCIP doesn't need the object
5576  * anymore, it is automatically released.
5577  *
5578  * E.g., if the user calls
5579  * \code
5580  * SCIPcreateVar(); // reference counter 1
5581  * SCIPaddVar(); // reference counter 2
5582  * SCIPreleaseVar(); // reference counter 1
5583  * \endcode
5584  * the reference counter will be 1 afterwards, and the variable will be destroyed, if SCIP frees the problem.
5585  * If the user wants to use this variable, e.g. for extracting statistics after SCIP was finished, the user must not call
5586  * SCIPreleaseVar() right after adding the variable, but before terminating the program.
5587  */
5588 
5589 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5590 /**@page PARAM How to add additional user parameters
5591  *
5592  * Users may add their own parameters to SCIP by calling SCIPaddXyzParam(). Using
5593  * this method, there are two possibilities for where to store the actual parameter value:
5594  * - If the given valueptr is NULL, SCIP stores the parameter value internally, and
5595  * the user can only access the value with the SCIPgetXyzParam() and
5596  * SCIPsetXyzParam() calls.
5597  * - If the given valueptr is not NULL, SCIP stores the parameter value at the given
5598  * address, and the user can directly manipulate the value at this address.
5599  * (S)he has to be careful with memory management in string parameters: when the
5600  * SCIPaddStringParam() method is called, the given address must hold a char*
5601  * pointer with value NULL. The default value is then copied into this pointer,
5602  * allocating memory with BMSallocMemoryArray(). If the parameter is changed, the
5603  * old string is freed with BMSfreeMemoryArray() and the new one is copied to a new
5604  * memory area allocated with BMSallocMemoryArray(). When the parameter is freed,
5605  * the memory is freed with BMSfreeMemoryArray().
5606  * The user should not interfere with this internal memory management. Accessing
5607  * the string parameter through the given valueptr is okay as long as it does not
5608  * involve reallocating memory for the string.
5609  *
5610  * In some cases, it is necessary to keep track of changes in a parameter.
5611  * If this is the case, the user can define a method by the PARAMCHGD callback and use this method as
5612  * the @c paramchgd parameter of the @c SCIPaddXyzParam() method, also giving a pointer to the data, which is
5613  * needed in this method, as @c paramdata. If this method is not NULL, it is called every time
5614  * the value of the parameter is changed.
5615  */
5616 
5617 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5618 /**@page DEBUG Debugging
5619  *
5620  * If you need to debug your own code that uses SCIP, here are some tips and tricks:
5621  *
5622  * - Use <b>asserts</b> in your code to show preconditions for the parameters, invariants and postconditions.
5623  * Assertions are boolean expressions which inevitably have to evaluate to <code>TRUE</code>. Consider the
5624  * following example, taken from the file src/scip/cons_linear.c:
5625  * \code
5626  * SCIP_RETCODE consdataCatchEvent(
5627  * SCIP* scip, /**< SCIP data structure *\/
5628  * SCIP_CONSDATA* consdata, /**< linear constraint data *\/
5629  * SCIP_EVENTHDLR* eventhdlr, /**< event handler to call for the event processing *\/
5630  * int pos /**< array position of variable to catch bound change events for *\/
5631  * )
5632  * {
5633  * assert(scip != NULL);
5634  * assert(consdata != NULL);
5635  * assert(eventhdlr != NULL);
5636  * assert(0 <= pos && pos < consdata->nvars);
5637  * ...
5638  * }
5639  * \endcode
5640  * As you can see, both pointers and integers are checked for valid values at the beginning of the
5641  * function <code>consdataCatchEvent()</code>. This is particularly important for, e.g., array indices like
5642  * the variable <code>pos</code> in this example, where using the <code>consdata->nvars[pos]</code>
5643  * pointer could result in unexspected behaviour
5644  * if the asserted precondition on <code>pos</code> were not matched and <pos> were an arbitrary index
5645  * outside the array range.
5646  *
5647  * - In order to activate assertions, use the <b>Debug mode</b> by compiling SCIP via
5648  * \code
5649  * make OPT=dbg
5650  * \endcode and run the code. See \ref MAKE for further information about compiler options for SCIP.
5651  *
5652  * - Spending only little extra time on
5653  * asserting preconditions saves most of the time spent on debugging!
5654  *
5655  * - Turn on <b>additional debug output</b> by adding the line
5656  * \code
5657  * #define SCIP_DEBUG
5658  * \endcode
5659  * at the top of SCIP files you want to analyze. This will output messages included in the code using
5660  * <code>SCIPdebugMessage()</code> (see \ref EXAMPLE_1).
5661  * We recommend to also use <code>SCIPdebugMessage()</code> in your own code for being able to activate
5662  * debug output in the same way.
5663  * - If available on your system, we recommend to use a debugger like <code>gdb</code>
5664  * to trace all function calls on the stack,
5665  * display values of certain expressions, manually break the running code, and so forth.
5666  * - If available on your system, you can use software like <a href="http://valgrind.org">valgrind</a> to check for uninitialized
5667  * values or segmentation faults.
5668  * - For checking the usage of SCIP memory, you can use
5669  * <code>SCIPprintMemoryDiagnostic()</code>. This outputs memory that is currently in use,
5670  * which can be useful after a <code>SCIPfree()</code> call.
5671  * - If there are memory leaks for which you cannot detect the origin, you can remake your code with the option NOBLKBUFMEM=true
5672  * (do not forget to clean your code before with <code>make OPT=... LPS=... clean</code>). After that valgrind (or similar) helps
5673  * to detect leaked memory.
5674  * - If your code cuts off a feasible solution, but you do not know which component is responsible,
5675  * you can define <code>SCIP_DEBUG_SOLUTION</code> in the file <code>debug.h</code> to be a filename
5676  * containing a solution in SCIP format (see \ref EXAMPLE_2).
5677  * This solution is then read and it is checked for every cut, whether the solution violates the cut.
5678  *
5679  * @section EXAMPLE_1 How to activate debug messages
5680  * For example, if we include a <code>\#define SCIP_DEBUG</code> at the top of \ref heur_oneopt.h, recompile SCIP
5681  * in DBG mode, and run the SCIP interactive shell to solve p0033.mps from the
5682  * <a href="http://miplib.zib.de/miplib3/miplib.html">MIPLIB 3.0</a> , we get some output like:
5683  * \code
5684  * SCIP version 1.1.0 [precision: 8 byte] [memory: block] [mode: debug] [LP solver: SoPlex 1.4.0]
5685  * Copyright (c) 2002-2014 Konrad-Zuse-Zentrum fuer Informationstechnik Berlin (ZIB)
5686  *
5687  * user parameter file <scip.set> not found - using default parameters
5688  *
5689  * SCIP> read check/IP/miplib/p0033.mps
5690  * original problem has 33 variables (33 bin, 0 int, 0 impl, 0 cont) and 16 constraints
5691  * SCIP> optimize
5692  * ...
5693  * 0.1s| 1 | 0 | 132 | 257k| 0 | 14 | 30 | 13 | 13 | 30 | 51 | 39 | 0 | 0 | 3.026472e+03 | 3.347000e+03 | 10.59%
5694  * [src/scip/heur_oneopt.c:332] debug: Row <R122> has activity 110
5695  * [src/scip/heur_oneopt.c:332] debug: Row <R123> has activity 216
5696  * ...
5697  * [src/scip/heur_oneopt.c:101] debug: Try to shift down variable <t_C157> with
5698  * [src/scip/heur_oneopt.c:102] debug: lb:<-0> <= val:<1> <= ub:<1> and obj:<171> by at most: <1>
5699  * [src/scip/heur_oneopt.c:135] debug: -> The shift value had to be reduced to <0>, because of row <R122>.
5700  * [src/scip/heur_oneopt.c:137] debug: lhs:<-1e+20> <= act:<110> <= rhs:<148>, colval:<-60>
5701  * ...
5702  * [src/scip/heur_oneopt.c:383] debug: Only one shiftcand found, var <t_C167>, which is now shifted by<-1.0>
5703  * k 0.1s| 1 | 0 | 132 | 258k| 0 | 14 | 30 | 13 | 13 | 30 | 51 | 39 | 0 | 0 | 3.026472e+03 | 3.164000e+03 | 4.54%
5704  * [src/scip/heur_oneopt.c:436] debug: found feasible shifted solution:
5705  * objective value: 3164.00000000012
5706  * C157 1 (obj:171)
5707  * C163 1 (obj:163)
5708  * C164 1 (obj:69)
5709  * C170 1 (obj:49)
5710  * C172 1 (obj:258)
5711  * C174 1 (obj:250)
5712  * C175 1 (obj:500)
5713  * C179 1 (obj:318)
5714  * C181 1 (obj:318)
5715  * C182 1 (obj:159)
5716  * C183 1.00000000000038 (obj:318)
5717  * C184 1 (obj:159)
5718  * C185 1 (obj:318)
5719  * C186 1 (obj:114)
5720  * [src/scip/heur_oneopt.c:498] debug: Finished 1-opt heuristic
5721  * ...
5722  * \endcode
5723  *
5724  * @section EXAMPLE_2 How to add a debug solution
5725  *
5726  * Continuing the example above, we finish the solving process.
5727  * The optimal solution can now be written to a file:
5728  * \code
5729  * SCIP> display solution
5730  *
5731  * objective value: 3089
5732  * C157 1 (obj:171)
5733  * C163 1 (obj:163)
5734  * C164 1 (obj:69)
5735  * C166 1 (obj:183)
5736  * C170 1 (obj:49)
5737  * C174 1 (obj:250)
5738  * C177 1 (obj:500)
5739  * C179 1 (obj:318)
5740  * C181 1 (obj:318)
5741  * C182 1 (obj:159)
5742  * C183 1 (obj:318)
5743  * C184 1 (obj:159)
5744  * C185 1 (obj:318)
5745  * C186 1 (obj:114)
5746  *
5747  * SCIP> write solution check/p0033.sol
5748  *
5749  * written solution information to file <check/p0033.sol>
5750  * \endcode
5751  *
5752  * If we afterwards use
5753  * <code>\#define SCIP_DEBUG_SOLUTION "check/p0033.sol"</code> in debug.h, recompile and run SCIP,
5754  * it will output:
5755  * \code
5756  * SCIP> read check/IP/miplib/p0033.mps
5757  * original problem has 33 variables (33 bin, 0 int, 0 impl, 0 cont) and 16 constraints
5758  * SCIP> optimize
5759  *
5760  * presolving:
5761  * ***** debug: reading solution file <check/p0033.sol>
5762  * ***** debug: read 15 non-zero entries
5763  * \endcode
5764  * Further debug output would only appear, if the solution was cut off in the solving process.
5765  * Of course, this is not the case! Hopefully...otherwise, please send a bug report ;-)
5766  */
5767 
5768 /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
5769 /**@page TEST How to run automated tests with SCIP
5770  *
5771  * SCIP comes along with a set of useful tools that allow to perform automated tests. The
5772  * following is a step-by-step guide from setting up the test environment for evaluation and
5773  * customization of test runs.
5774  *
5775  *
5776  * @section SETUP Setting up the test environment
5777  *
5778  * At first you should create a file listing all problem instances that should be part of the test.
5779  * This file has to be located in the the directory <code>scip/check/testset/</code>
5780  * and has to have the file extension <code>.test</code>, e.g., <code>testrun.test</code>,
5781  * in order to be found by the <code>scip/check/check.sh</code> script.
5782  * \n
5783  * All test problems can be listed in the <code>test</code>-file by a relative path,
5784  * e.g., <code>../../problems/instance1.lp</code> or absolute path, e.g., <code>/home/problems/instance2.mps</code>
5785  * in this file. Only one problem should be listed each on line (since the command <code>cat</code> is used to parse this file).
5786  * Note that these problems have to be readable for SCIP in order to solve them.
5787  * However, you can use different file formats.
5788  *
5789  * Optionally, you can provide a solution file in the <code>scip/check/testset/</code> directory containing
5790  * known information about the feasibility and the best known objective values for the test instances.
5791  * SCIP can use these values to verify the results. The file has to have the same basename as the
5792  * <code>.test</code>-file, i.e., in our case <code>testrun.solu</code>. One line can only contain
5793  * information about one test instance. A line has to start with the type of information given:
5794  *
5795  * - <code>=opt=</code> stating that a problem name with an optimal objective value follows
5796  * - <code>=best=</code> stating that a problem name with a best know objective value follows
5797  * - <code>=inf=</code> stating that a problem name follows which is infeasible
5798  *
5799  * With these information types you can encode for an instance named <code>instance1.lp</code> the following
5800  * information:
5801  * - The instance has a known optimal (objective) value of 10.
5802  * \code
5803  * =opt= instance1 10
5804  * \endcode
5805  * - The instance has a best known solution with objective value 15.
5806  * \code
5807  * =best= instance1 15
5808  * \endcode
5809  * - The instance is feasible (but has no objective function or we don't know a solution value)
5810  * \code
5811  * =feas= instance1
5812  * \endcode
5813  * - The instance is infeasible.
5814  * \code
5815  * =inf= instance1
5816  * \endcode
5817  *
5818  * If you don't know whether the instance is feasible or not (so the status is unknown),
5819  * you can omit the instance in the <code>solu</code>-file or write
5820  * \code
5821  * =unkn= instance1
5822  * \endcode
5823  *
5824  * <b>Note that in all lines the file extension of the file name is omitted.</b>
5825  * \n
5826  * See the files <code>scip/check/testset/short.test</code> and <code>scip/check/testset/short.solu</code>
5827  * for an example of a <code>test</code>-file and its corresponding <code>solu</code>-file.
5828  *
5829  *
5830  *
5831  * @section STARTING Starting a test run
5832  *
5833  *
5834  * \code
5835  * make TEST=testrun test
5836  * \endcode
5837  *
5838  * in the SCIP root directory. Note that <code>testrun</code> is exactly the basename of our
5839  * <code>test</code>-file (<code>testrun.test</code>). This will cause SCIP to solve our test instances
5840  * one after another and to create various output files (see \ref EVAL).
5841  *
5842  *
5843  * @section EVAL Evaluating a test run
5844  *
5845  * During computation, SCIP automatically creates the directory <code>scip/check/results/</code>
5846  * (if it does not already exist) and stores the following output files there.
5847  *
5848  * \arg <code>*.out</code> - output of <code>stdout</code>
5849  * \arg <code>*.err</code> - output of <code>stderr</code>
5850  * \arg <code>*.set</code> - copy of the used settings file
5851  *
5852  * \arg <code>*.res</code> - ASCII table containing a summary of the computational results
5853  * \arg <code>*.tex</code> - TeX table containing a summary of the computational results
5854  * \arg <code>*.pav</code> - <a href="http://www.gamsworld.org/performance/paver/">PAVER</a> output
5855  *
5856  * The last three files in the above list, i.e., the files containing a summary of the computational results,
5857  * can also be generated manually. Therefore the user has to call the <code>evalcheck.sh</code> script in the
5858  * @c check directory with the corresponding @c out file as argument. For example, this may be useful if the user stopped the
5859  * test before it was finished, in which case the last three files will not be automatically generated by SCIP.
5860  *
5861  * The last column of the ASCII summary table contains the solver status. We distinguish the following statuses: (in order of priority)
5862  *
5863  * \arg abort: solver broke before returning solution
5864  * \arg fail: solver cut off a known feasible solution (value of the <code>solu</code>-file is beyond the dual bound;
5865  * especially of problem is claimed to be solved but solution is not the optimal solution)
5866  * \arg ok: solver solved problem with the value in solu-file
5867  * \arg solved: solver solved problem which has no (optimal) value in solu-file (since we here cannot detect the direction
5868  * of optimization, it is possible that a solver claims an optimal solution which contradicts a known feasible solution)
5869  * \arg better: solver found solution better than known best solution (or no solution was noted in the <code>solu</code>-file so far)
5870  * \arg gaplimit, sollimit: solver reached gaplimit or limit of number of solutions (at present: only in SCIP)
5871  * \arg timeout: solver reached any other limit (like time or nodes)
5872  * \arg unknown: otherwise
5873  *
5874  * Additionally the <code>evalcheck.sh</code> script can generate a <code>solu</code>-file by calling
5875  * \code
5876  * ./evalcheck.sh writesolufile=1 NEWSOLUFILE=<solu-file> <out-file>
5877  * \endcode
5878  * where <code><solu-file></code> denotes the filename of the new file where the solutions shall be
5879  * (and <code><out-file></code> denotes the output (<code>.out</code>) files to evaluate).
5880  *
5881  * Another feature can be enabled by calling:
5882  * \code
5883  * ./evalcheck.sh printsoltimes=1 ...
5884  * \endcode
5885  * The output has two additional columns containing the solving time until the first and the best solution was found.
5886  *
5887  *
5888  * @b Note: The @em basename of all these files is the same and has the following structure
5889  * which allows us to reconstruct the test run:
5890  *
5891  * \code
5892  * check.<test name>.<binary>.<machine name>.<setting name>
5893  * \endcode
5894  *
5895  * \arg <<code>test name</code>> indicates the name of the the test file, e.g., <code>testrun</code>
5896  * \arg <<code>binary</code>> defines the used binary, e.g., <code>scip-1.1.0.linux.x86.gnu.opt.spx</code>
5897  * \arg <<code>machine name</code>> tells the name of the machine, e.g., <code>mycomputer</code>
5898  * \arg <<code>setting name</code>> denotes the name of the used settings, e.g., <code>default</code>
5899  * means the (SCIP) default settings were used
5900  *
5901  * Using the examples out of the previous listing the six file names would have the name:
5902  *
5903  * \code
5904  * check.testrun.scip-1.1.0.linux.x86.gnu.opt.spx.mycomputer.default.<out,err,set,res,tex,pav>
5905  * \endcode
5906  *
5907  *
5908  * @section USING Using customized setting files
5909  *
5910  * It is possible to use customized settings files for the test run instead of testing SCIP with default settings.
5911  * These have to be placed in the directory <code>scip/settings/</code>.
5912  *
5913  * @b Note: Accessing setting files in subfolders of the @c settings directory is currently not supported.
5914  *
5915  * To run SCIP with a custom settings file, say for example <code>fast.set</code>, we call
5916  *
5917  * \code
5918  * make TEST=testrun SETTINGS=fast test
5919  * \endcode
5920  *
5921  * in the SCIP root directory.
5922  *
5923  *
5924  * @section ADVANCED Advanced options
5925  *
5926  * We can further customize the test run by specifying the following options in the <code>make</code> call:
5927  *
5928  * \arg <code>TIME</code> - time limit for each test instance in seconds [default: 3600]
5929  * \arg <code>NODES</code> - node limit [default: 2100000000]
5930  * \arg <code>MEM</code> - memory limit in MB [default: 1536]
5931  * \arg <code>DISPFREQ</code> - display frequency of the output [default: 10000]
5932  * \arg <code>FEASTOL</code> - LP feasibility tolerance for constraints [default: "default"]
5933  * \arg <code>LOCK</code> - should the test run be locked to prevent other machines from performing the same test run [default: "false"]
5934  * \arg <code>CONTINUE</code> - continue the test run if it was previously aborted [default: "false"]
5935  * \arg <code>VALGRIND</code> - run valgrind on the SCIP binary; errors and memory leaks found by valgrind are reported as fails [default: "false"]
5936  *
5937  *
5938  * @section COMPARE Comparing test runs for different settings
5939  *
5940  * Often test runs are performed on the basis of different settings. In this case, it is useful to
5941  * have a performance comparison. For this purpose, we can use the <code>allcmpres.sh</code> script in
5942  * the @c check directory.
5943  *
5944  * Suppose, we performed our test run with two different settings, say <code>fast.set</code> and
5945  * <code>slow.set</code>. Assuming that all other parameters (including the SCIP binary), were the same,
5946  * we may have the following <code>res</code>-files in the directory <code>scip/check/results/</code>
5947  *
5948  * \code
5949  * check.testrun.scip-1.1.0.linux.x86.gnu.opt.spx.mycomputer.fast.res
5950  * check.testrun.scip-1.1.0.linux.x86.gnu.opt.spx.mycomputer.slow.res
5951  * \endcode
5952  *
5953  * For a comparison of both computations, we simply call
5954  *
5955  * \code
5956  * allcmpres.sh results/check.testrun.scip-1.1.0.linux.x86.gnu.opt.spx.mycomputer.fast.res \
5957  * results/check.testrun.scip-1.1.0.linux.x86.gnu.opt.spx.mycomputer.slow.res
5958  * \endcode
5959  *
5960  * in the @c check directory. This produces an ASCII table on the console that provide a detailed
5961  * performance comparison of both test runs. Note that the first <code>res</code>-file serves as reference
5962  * computation. The following list explains the output.
5963  * (The term "solver" can be considered as the combination of SCIP with a specific setting file.)
5964  *
5965  * \arg <code>Nodes</code> - Number of processed branch-and-bound nodes.
5966  * \arg <code>Time</code> - Computation time in seconds.
5967  * \arg <code>F</code> - If no feasible solution was found, then '#', empty otherwise.
5968  * \arg <code>NodQ</code> - Equals Nodes(i) / Nodes(0), where 'i' denotes the current solver and '0' stands for the reference solver.
5969  * \arg <code>TimQ</code> - Equals Time(i) / Time(0).
5970  * \arg <code>bounds check</code> - Status of the primal and dual bound check.
5971  *
5972  * \arg <code>proc</code> - Number of instances processed.
5973  * \arg <code>eval</code> - Number of instances evaluated (bounds check = "ok", i.e., solved to optimality
5974  * within the time and memory limit and result is correct). Only these instances are used in the calculation
5975  * of the mean values.
5976  * \arg <code>fail</code> - Number of instances with bounds check = "fail".
5977  * \arg <code>time</code> - Number of instances with timeout.
5978  * \arg <code>solv</code> - Number of instances correctly solved within the time limit.
5979  * \arg <code>wins</code> - Number of instances on which the solver won (i.e., the
5980  * solver was at most 10% slower than the fastest solver OR had the best
5981  * primal bound in case the instance was not solved by any solver within
5982  * the time limit).
5983  * \arg <code>bett</code> - Number of instances on which the solver was better than the
5984  * reference solver (i.e., more than 10% faster).
5985  * \arg <code>wors</code> - Number of instances on which the solver was worse than the
5986  * reference solver (i.e., more than 10% slower).
5987  * \arg <code>bobj</code> - Number of instances on which the solver had a better primal
5988  * bound than the reference solver (i.e., a difference larger than 10%).
5989  * \arg <code>wobj</code> - Number of instances on which the solver had a worse primal
5990  * bound than the reference solver (i.e., a difference larger than 10%).
5991  * \arg <code>feas</code> - Number of instances for which a feasible solution was found.
5992  * \arg <code>gnodes</code> - Geometric mean of the processed nodes over all evaluated instances.
5993  * \arg <code>shnodes</code> - Shifted geometric mean of the processed nodes over all evaluated instances.
5994  * \arg <code>gnodesQ</code> - Equals nodes(i) / nodes(0), where 'i' denotes the current
5995  * solver and '0' stands for the reference solver.
5996  * \arg <code>shnodesQ</code> - Equals shnodes(i) / shnodes(0).
5997  * \arg <code>gtime</code> - Geometric mean of the computation time over all evaluated instances.
5998  * \arg <code>shtime</code> - Shifted geometric mean of the computation time over all evaluated instances.
5999  * \arg <code>gtimeQ</code> - Equals time(i) / time(0).
6000  * \arg <code>shtimeQ</code> - Equals shtime(i) / shtime(0).
6001  * \arg <code>score</code> - N/A
6002  *
6003  * \arg <code>all</code> - All solvers.
6004  * \arg <code>optimal auto settings</code> - Theoretical result for a solver that performed 'best of all' for every instance.
6005  * \arg <code>diff</code> - Solvers with instances that differ from the reference solver in the number of
6006  * processed nodes or in the total number of simplex iterations.
6007  * \arg <code>equal</code> - Solvers with instances whose number of processed nodes and total number of
6008