1    	/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
2    	/*                                                                           */
3    	/*                  This file is part of the program and library             */
4    	/*         SCIP --- Solving Constraint Integer Programs                      */
5    	/*                                                                           */
6    	/*  Copyright (c) 2002-2023 Zuse Institute Berlin (ZIB)                      */
7    	/*                                                                           */
8    	/*  Licensed under the Apache License, Version 2.0 (the "License");          */
9    	/*  you may not use this file except in compliance with the License.         */
10   	/*  You may obtain a copy of the License at                                  */
11   	/*                                                                           */
12   	/*      http://www.apache.org/licenses/LICENSE-2.0                           */
13   	/*                                                                           */
14   	/*  Unless required by applicable law or agreed to in writing, software      */
15   	/*  distributed under the License is distributed on an "AS IS" BASIS,        */
16   	/*  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. */
17   	/*  See the License for the specific language governing permissions and      */
18   	/*  limitations under the License.                                           */
19   	/*                                                                           */
20   	/*  You should have received a copy of the Apache-2.0 license                */
21   	/*  along with SCIP; see the file LICENSE. If not visit scipopt.org.         */
22   	/*                                                                           */
23   	/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
24   	
25   	/**@file   type_nlhdlr.h
26   	 * @ingroup TYPEDEFINITIONS
27   	 * @brief  type definitions related to nonlinear handlers of nonlinear constraints
28   	 * @author Ksenia Bestuzheva
29   	 * @author Benjamin Mueller
30   	 * @author Felipe Serrano
31   	 * @author Stefan Vigerske
32   	 *
33   	 *  This file defines the interface for nonlinear handlers.
34   	 *
35   	 *  - \ref NLHDLRS "List of available nonlinear handlers"
36   	 */
37   	
38   	/** @defgroup DEFPLUGINS_NLHDLR Default nonlinear handlers
39   	 *  @ingroup DEFPLUGINS
40   	 *  @brief implementation files (.c files) of the default nonlinear handlers of SCIP
41   	 */
42   	
43   	#ifndef SCIP_TYPE_NLHDLR_H_
44   	#define SCIP_TYPE_NLHDLR_H_
45   	
46   	#include "scip/type_expr.h"
47   	#include "scip/type_cons.h"
48   	#include "scip/type_misc.h"
49   	
50   	#define SCIP_NLHDLR_METHOD_NONE       0x0u   /**< no enforcement */
51   	#define SCIP_NLHDLR_METHOD_SEPABELOW  0x1u   /**< separation for expr <= auxvar, thus might estimate expr from below */
52   	#define SCIP_NLHDLR_METHOD_SEPAABOVE  0x2u   /**< separation for expr >= auxvar, thus might estimate expr from above */
53   	#define SCIP_NLHDLR_METHOD_SEPABOTH   (SCIP_NLHDLR_METHOD_SEPABELOW | SCIP_NLHDLR_METHOD_SEPAABOVE)  /**< separation for expr == auxvar */
54   	#define SCIP_NLHDLR_METHOD_ACTIVITY   0x4u   /**< activity computation (interval evaluation) and propagation (reverse propagation) */
55   	#define SCIP_NLHDLR_METHOD_ALL        (SCIP_NLHDLR_METHOD_SEPABOTH | SCIP_NLHDLR_METHOD_ACTIVITY) /**< all enforcement methods */
56   	
57   	typedef unsigned int SCIP_NLHDLR_METHOD; /**< nlhdlr methods bitflags */
58   	
59   	/** nonlinear handler copy callback
60   	 *
61   	 * The method includes the nonlinear handler into a nonlinear constraint handler.
62   	 *
63   	 * This method is usually called when doing a copy of a nonlinear constraint handler.
64   	 *
65   	 * \param[in] targetscip      target SCIP main data structure
66   	 * \param[in] targetconshdlr  target nonlinear constraint handler
67   	 * \param[out] sourceconshdlr nonlinear constraint handler in source SCIP
68   	 * \param[out] sourcenlhdlr   nonlinear handler in source SCIP
69   	 */
70   	#define SCIP_DECL_NLHDLRCOPYHDLR(x) SCIP_RETCODE x (\
71   	   SCIP*          targetscip,     \
72   	   SCIP_CONSHDLR* targetconshdlr, \
73   	   SCIP_CONSHDLR* sourceconshdlr, \
74   	   SCIP_NLHDLR*   sourcenlhdlr)
75   	
76   	/** callback to free data of handler
77   	 *
78   	 * \param[in] scip       SCIP data structure
79   	 * \param[in] nlhdlr     nonlinear handler
80   	 * \param[in] nlhdlrdata nonlinear handler data to be freed
81   	 */
82   	#define SCIP_DECL_NLHDLRFREEHDLRDATA(x) SCIP_RETCODE x (\
83   	   SCIP*             scip,   \
84   	   SCIP_NLHDLR*      nlhdlr, \
85   	   SCIP_NLHDLRDATA** nlhdlrdata)
86   	
87   	/** callback to free expression specific data
88   	 *
89   	 * \param[in] scip           SCIP data structure
90   	 * \param[in] nlhdlr         nonlinear handler
91   	 * \param[in] expr           expression
92   	 * \param[in] nlhdlrexprdata nonlinear handler expression data to be freed
93   	 */
94   	#define SCIP_DECL_NLHDLRFREEEXPRDATA(x) SCIP_RETCODE x (\
95   	   SCIP*                 scip,   \
96   	   SCIP_NLHDLR*          nlhdlr, \
97   	   SCIP_EXPR*            expr,   \
98   	   SCIP_NLHDLREXPRDATA** nlhdlrexprdata)
99   	
100  	/** callback to be called in initialization (called after problem was transformed)
101  	 *
102  	 * \param[in] scip   SCIP data structure
103  	 * \param[in] nlhdlr nonlinear handler
104  	 */
105  	#define SCIP_DECL_NLHDLRINIT(x) SCIP_RETCODE x (\
106  	   SCIP*        scip, \
107  	   SCIP_NLHDLR* nlhdlr)
108  	
109  	/** callback to be called in deinitialization (called before transformed problem is freed)
110  	 *
111  	 * \param[in] scip   SCIP data structure
112  	 * \param[in] nlhdlr nonlinear handler
113  	 */
114  	#define SCIP_DECL_NLHDLREXIT(x) SCIP_RETCODE x (\
115  	   SCIP*        scip, \
116  	   SCIP_NLHDLR* nlhdlr)
117  	
118  	/** callback to detect structure in expression
119  	 *
120  	 * The nonlinear handler shall analyze the current expression and decide whether it wants to contribute
121  	 * in enforcing the relation between this expression (`expr`) and its descendants (e.g., children) via
122  	 * linear under- or overestimation, cut generation, and/or activity computation and propagation.
123  	 * For linear under- or overestimation and cut generation, an auxiliary variable (`auxvar`) can be assumed to
124  	 * be associated with `expr` and auxiliary variables may be requested in descendant expressions.
125  	 *
126  	 * We distinguish the following enforcement methods:
127  	 * - \ref SCIP_NLHDLR_METHOD_SEPABELOW : linear underestimation of `expr` or cut generation for the relation `expr` &le; `auxvar` (denoted as "below")
128  	 * - \ref SCIP_NLHDLR_METHOD_SEPAABOVE : linear overestimation of `expr` or cut generation for the relation `expr` &ge; `auxvar` (denoted as "above")
129  	 * - \ref SCIP_NLHDLR_METHOD_ACTIVITY  : domain propagation (i.e., constant under/overestimation) for the relation `expr` = `auxvar`.
130  	 *
131  	 * On input, parameter `enforcing` indicates for any of these methods, whether
132  	 * - it is not necessary to have such a method, e.g., because no `auxvar` will exist for `expr`, or no one uses or sets activities of this expression,
133  	 *   or because analysis of the expression has shown that a relation like `expr` &ge; `auxvar` is not necessary to be satisfied,
134  	 * - or there already exists a nonlinear handler that will provide this method in an "enforcement" sense, that is,
135  	 *   it believes that no one else could provide this method in a stronger sense. (This is mainly used by nlhdlr_default to check whether
136  	 *   it should still reach out to the exprhdlr or whether it would be dominated by some nonlinear handler.)
137  	 *
138  	 * The DETECT callback shall augment the `enforcing` bitmask by setting the enforcement methods it wants to provide in an "enforcement" sense.
139  	 *
140  	 * Additionally, the `participating` bitmask shall be set if the nonlinear handler wants to be called on this expression at all.
141  	 * Here, it shall set all methods that it wants to provide, which are those set in `enforcing`, but additionally those where it wants
142  	 * to participate but leave enforcement to another nonlinear handler.
143  	 * This can be useful for nonlinear handlers that do not implement a complete enforcement, e.g., a handler that only contributes
144  	 * cutting planes in some situations only.
145  	 *
146  	 * A nonlinear handler will be called only for those callbacks that it mentioned in `participating`, which is
147  	 * - \ref SCIP_DECL_NLHDLRENFO "ENFO" and/or \ref SCIP_DECL_NLHDLRESTIMATE "ESTIMATE" will be called with `overestimate==FALSE` if \ref SCIP_NLHDLR_METHOD_SEPABELOW has been set
148  	 * - \ref SCIP_DECL_NLHDLRENFO "ENFO" and/or \ref SCIP_DECL_NLHDLRESTIMATE "ESTIMATE" will be called with `overestimate==TRUE`  if \ref SCIP_NLHDLR_METHOD_SEPAABOVE has been set
149  	 * - \ref SCIP_DECL_NLHDLRINTEVAL "INTEVAL" and/or \ref SCIP_DECL_NLHDLRREVERSEPROP "REVERSEPROP" will be called if \ref SCIP_NLHDLR_METHOD_ACTIVITY has been set
150  	 *
151  	 * If \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE has been set, then at least one of the
152  	 * callbacks \ref SCIP_DECL_NLHDLRENFO "ENFO" and \ref SCIP_DECL_NLHDLRESTIMATE "ESTIMATE" needs to be implemented.
153  	 * Also \ref SCIP_DECL_NLHDLREVALAUX "EVALAUX" will be called in this case.
154  	 * If \ref SCIP_NLHDLR_METHOD_ACTIVITY has been set, then at least one of \ref SCIP_DECL_NLHDLRINTEVAL "INTEVAL" and
155  	 * \ref SCIP_DECL_NLHDLRREVERSEPROP "REVERSEPROP" needs to be implemented.
156  	 * If the nonlinear handler chooses not to participate, then it must not set `nlhdlrexprdata` and can leave `participating` at its
157  	 * initial value (\ref SCIP_NLHDLR_METHOD_NONE).
158  	 *
159  	 * Additionally, a nonlinear handler that decides to participate in any of the enforcement methods must call
160  	 * @ref SCIPregisterExprUsageNonlinear() for every subexpression that it will use and indicate whether
161  	 * - it will use an auxiliary variable in \ref SCIP_DECL_NLHDLRENFO "ENFO" or \ref SCIP_DECL_NLHDLRESTIMATE "ESTIMATE",
162  	 * - it will use activity for some subexpressions when computing estimators or cuts, and
163  	 * - it will use activity for some subexpressions when in \ref SCIP_DECL_NLHDLRINTEVAL "INTEVAL" or \ref SCIP_DECL_NLHDLRREVERSEPROP "REVERSEPROP".
164  	 *
165  	 * @note Auxiliary variables do not exist in subexpressions during DETECT and are not created by a call to @ref SCIPregisterExprUsageNonlinear().
166  	 *   They will be available when the \ref SCIP_DECL_NLHDLRINITSEPA "INITSEPA" callback is called.
167  	 *
168  	 * \param[in] scip              SCIP data structure
169  	 * \param[in] conshdlr          nonlinear constraint handler
170  	 * \param[in] nlhdlr            nonlinear handler
171  	 * \param[in] expr              expression to analyze
172  	 * \param[in] cons              the constraint that expression defines, or NULL when the expr does not define any constraint, that is, when it is not the root of an expression of a constraint
173  	 * \param[in,out] enforcing     enforcement methods that are provided by some nonlinear handler (to be updated by detect callback)
174  	 * \param[out] participating    enforcement methods that this nonlinear handler should be called for (to be set by detect callback), initialized to SCIP_NLHDLR_METHOD_NONE
175  	 * \param[out] nlhdlrexprdata   nlhdlr's expr data to be stored in expr, can only be set to non-NULL if success is set to TRUE
176  	 */
177  	#define SCIP_DECL_NLHDLRDETECT(x) SCIP_RETCODE x (\
178  	   SCIP*                 scip,          \
179  	   SCIP_CONSHDLR*        conshdlr,      \
180  	   SCIP_NLHDLR*          nlhdlr,        \
181  	   SCIP_EXPR*            expr,          \
182  	   SCIP_CONS*            cons,          \
183  	   SCIP_NLHDLR_METHOD*   enforcing,     \
184  	   SCIP_NLHDLR_METHOD*   participating, \
185  	   SCIP_NLHDLREXPRDATA** nlhdlrexprdata)
186  	
187  	/** auxiliary evaluation callback of nonlinear handler
188  	 *
189  	 * Evaluates the expression w.r.t. the auxiliary variables that were introduced by the nonlinear handler (if any).
190  	 * The method is used to determine the violation of the relation that the nonlinear handler attempts to enforce.
191  	 * During enforcement, this violation value is used to decide whether estimation/separation callbacks should be called.
192  	 *
193  	 * It can be assumed that the expression itself has been evaluated in the given sol.
194  	 *
195  	 * \param[in]  scip           SCIP data structure
196  	 * \param[in]  nlhdlr         nonlinear handler
197  	 * \param[in]  expr           expression to evaluate
198  	 * \param[in]  nlhdlrexprdata expression specific data of the nonlinear handler
199  	 * \param[out] auxvalue       buffer to store value of expression w.r.t. auxiliary variables
200  	 * \param[in]  sol            point to evaluate
201  	 */
202  	#define SCIP_DECL_NLHDLREVALAUX(x) SCIP_RETCODE x (\
203  	   SCIP*                scip,           \
204  	   SCIP_NLHDLR*         nlhdlr,         \
205  	   SCIP_EXPR*           expr,           \
206  	   SCIP_NLHDLREXPRDATA* nlhdlrexprdata, \
207  	   SCIP_Real*           auxvalue,       \
208  	   SCIP_SOL*            sol)
209  	
210  	/** nonlinear handler interval evaluation (activity computation) callback
211  	 *
212  	 * The method computes an interval that contains the image (range) of the expression.
213  	 *
214  	 * \param[in] scip           SCIP main data structure
215  	 * \param[in] nlhdlr         nonlinear handler
216  	 * \param[in] expr           expression
217  	 * \param[in] nlhdlrexprdata expression specific data of the nonlinear handler
218  	 * \param[in,out] interval   buffer where to store interval (on input: current interval for expr, on output: computed interval for expr)
219  	 * \param[in] intevalvar     callback to be called when interval evaluating a variable
220  	 * \param[in] intevalvardata data to be passed to intevalvar callback
221  	 */
222  	#define SCIP_DECL_NLHDLRINTEVAL(x) SCIP_RETCODE x (\
223  	   SCIP*                scip,                \
224  	   SCIP_NLHDLR*         nlhdlr,              \
225  	   SCIP_EXPR*           expr,                \
226  	   SCIP_NLHDLREXPRDATA* nlhdlrexprdata,      \
227  	   SCIP_INTERVAL*       interval,            \
228  	   SCIP_DECL_EXPR_INTEVALVAR((*intevalvar)), \
229  	   void*                intevalvardata)
230  	
231  	/** nonlinear handler callback for reverse propagation
232  	 *
233  	 * The method propagates the given bounds over the arguments of an expression.
234  	 * The arguments of an expression are other expressions and the tighter intervals should be passed
235  	 * to the corresponding argument (expression) via SCIPtightenExprIntervalNonlinear().
236  	 *
237  	 * \param[in] scip           SCIP main data structure
238  	 * \param[in] conshdlr       nonlinear constraint handler
239  	 * \param[in] nlhdlr         nonlinear handler
240  	 * \param[in] expr           expression
241  	 * \param[in] nlhdlrexprdata expression specific data of the nonlinear handler
242  	 * \param[in] bounds         the bounds on the expression that should be propagated
243  	 * \param[out] infeasible    buffer to store whether an expression's bounds were propagated to an empty interval
244  	 * \param[out] nreductions   buffer to store the number of interval reductions of all children
245  	 */
246  	#define SCIP_DECL_NLHDLRREVERSEPROP(x) SCIP_RETCODE x (\
247  	   SCIP*                scip,           \
248  	   SCIP_CONSHDLR*       conshdlr,       \
249  	   SCIP_NLHDLR*         nlhdlr,         \
250  	   SCIP_EXPR*           expr,           \
251  	   SCIP_NLHDLREXPRDATA* nlhdlrexprdata, \
252  	   SCIP_INTERVAL        bounds,         \
253  	   SCIP_Bool*           infeasible,     \
254  	   int*                 nreductions)
255  	
256  	/** separation initialization method of a nonlinear handler (called during CONSINITLP)
257  	 *
258  	 * The method shall initialize the separation data of the nonlinear handler, if any, and add initial cuts to the LP relaxation.
259  	 *
260  	 * \param[in] scip           SCIP main data structure
261  	 * \param[in] conshdlr       nonlinear constraint handler
262  	 * \param[in] cons           nonlinear constraint
263  	 * \param[in] nlhdlr         nonlinear handler
264  	 * \param[in] nlhdlrexprdata exprdata of nonlinear handler
265  	 * \param[in] expr           expression
266  	 * \param[in] overestimate   whether the expression needs to be overestimated
267  	 * \param[in] underestimate  whether the expression needs to be underestimated
268  	 * \param[out] infeasible    buffer to store whether infeasibility was detected while building the LP
269  	 */
270  	#define SCIP_DECL_NLHDLRINITSEPA(x) SCIP_RETCODE x (\
271  	   SCIP*                scip,           \
272  	   SCIP_CONSHDLR*       conshdlr,       \
273  	   SCIP_CONS*           cons,           \
274  	   SCIP_NLHDLR*         nlhdlr,         \
275  	   SCIP_EXPR*           expr,           \
276  	   SCIP_NLHDLREXPRDATA* nlhdlrexprdata, \
277  	   SCIP_Bool            overestimate,   \
278  	   SCIP_Bool            underestimate,  \
279  	   SCIP_Bool*           infeasible)
280  	
281  	/** separation deinitialization method of a nonlinear handler (called during CONSEXITSOL)
282  	 *
283  	 * The method shall deinitialize the separation data of the nonlinear handler, if any.
284  	 *
285  	 * \param[in] scip           SCIP main data structure
286  	 * \param[in] nlhdlr         nonlinear handler
287  	 * \param[in] nlhdlrexprdata exprdata of nonlinear handler
288  	 * \param[in] expr           expression
289  	 */
290  	#define SCIP_DECL_NLHDLREXITSEPA(x) SCIP_RETCODE x (\
291  	   SCIP*                scip,   \
292  	   SCIP_NLHDLR*         nlhdlr, \
293  	   SCIP_EXPR*           expr,   \
294  	   SCIP_NLHDLREXPRDATA* nlhdlrexprdata)
295  	
296  	/** nonlinear handler separation and enforcement callback
297  	 *
298  	 * The method tries to separate the given solution from the set defined by either
299  	 * <pre>
300  	 *   expr - auxvar <= 0 (if !overestimate)
301  	 * </pre>
302  	 * or
303  	 * <pre>
304  	 *   expr - auxvar >= 0 (if  overestimate),
305  	 * </pre>
306  	 * where `auxvar = SCIPgetExprAuxVarNonlinear(expr)`.
307  	 *
308  	 * It can do so by
309  	 * - separation, i.e., finding an affine hyperplane (a cut) that separates the given point,
310  	 * - bound tightening, i.e., changing bounds on a variable so that the given point is outside the updated domain,
311  	 * - adding branching scores to potentially split the current problem into 2 subproblems
312  	 *
313  	 * If parameter `inenforcement` is FALSE, then only the first option (separation) is allowed.
314  	 *
315  	 * If the nonlinear handler always separates by computing a linear under- or overestimator of expr,
316  	 * then it could be advantageous to implement the \ref SCIP_DECL_NLHDLRESTIMATE "ESTIMATE" callback instead.
317  	 *
318  	 * Note, that the nonlinear handler may also choose to separate for a relaxation of the mentioned sets,
319  	 * e.g., `expr` &le; upperbound(`auxvar`)  or  `expr` &ge; lowerbound(`auxvar`).
320  	 * This is especially useful in situations where `expr` is the root expression of a constraint
321  	 * and it is sufficient to satisfy `lhs` &le; `expr` &le; `rhs`.
322  	 * cons_nonlinear ensures that `lhs` &le; lowerbound(`auxvar`) and upperbound(`auxvar`) &le; `rhs`.
323  	 *
324  	 * cons_nonlinear may call this callback first with `allowweakcuts` = FALSE and repeat later with
325  	 * `allowweakcuts` = TRUE, if it didn't succeed to enforce a solution without using weak cuts.
326  	 * If in enforcement and the nonlinear handler cannot enforce by separation or bound tightening, it should register
327  	 * branching scores for those expressions where branching may help to compute tighter cuts in children.
328  	 *
329  	 * The nonlinear handler must set `result` to \ref SCIP_SEPARATED if it added a cut,
330  	 * to \ref SCIP_REDUCEDDOM if it added a bound change, and
331  	 * to \ref SCIP_BRANCHED if it added branching scores.
332  	 * Otherwise, it may set result to \ref SCIP_DIDNOTRUN or \ref SCIP_DIDNOTFIND.
333  	 *
334  	 * Parameter `cons` gives the constraint that is currently enforced.
335  	 * Note that `expr` does not need to be the root of this constraint, i.e., `SCIPgetExprNonlinear(cons)==expr` may not hold.
336  	 * If an expression appears in several constraints, it is not well defined which constraint is given in `cons`.
337  	 * The main purpose of `cons` is to provide a constraint source for LP rows that are added in this callback.
338  	 *
339  	 * \param[in] scip           SCIP main data structure
340  	 * \param[in] conshdlr       nonlinear constraint handler
341  	 * \param[in] cons           nonlinear constraint that is currently enforced
342  	 * \param[in] nlhdlr         nonlinear handler
343  	 * \param[in] expr           expression
344  	 * \param[in] nlhdlrexprdata expression specific data of the nonlinear handler
345  	 * \param[in] sol            solution to be separated (NULL for the LP solution)
346  	 * \param[in] auxvalue       current value of expression w.r.t. auxiliary variables as obtained from \ref SCIP_DECL_NLHDLREVALAUX "EVALAUX"
347  	 * \param[in] overestimate   whether the expression needs to be over- or underestimated
348  	 * \param[in] allowweakcuts  whether we should only look for "strong" cuts, or anything that separates is fine
349  	 * \param[in] separated      whether another nonlinear handler already added a cut for this expression
350  	 * \param[in] inenforcement  whether we are in enforcement, or only in separation
351  	 * \param[out] result        pointer to store the result
352  	 */
353  	#define SCIP_DECL_NLHDLRENFO(x) SCIP_RETCODE x (\
354  	   SCIP*                scip,            \
355  	   SCIP_CONSHDLR*       conshdlr,        \
356  	   SCIP_CONS*           cons,            \
357  	   SCIP_NLHDLR*         nlhdlr,          \
358  	   SCIP_EXPR*           expr,            \
359  	   SCIP_NLHDLREXPRDATA* nlhdlrexprdata,  \
360  	   SCIP_SOL*            sol,             \
361  	   SCIP_Real            auxvalue,        \
362  	   SCIP_Bool            overestimate,    \
363  	   SCIP_Bool            allowweakcuts,   \
364  	   SCIP_Bool            separated,       \
365  	   SCIP_Bool            addbranchscores, \
366  	   SCIP_RESULT*         result)
367  	
368  	/** nonlinear handler under/overestimation callback
369  	 *
370  	 * The method tries to compute linear under- or overestimators of `expr` that are as tight as possible at a given point.
371  	 * Note that the cons_nonlinear handler adds an auxvar into a rowprep automatically after this callback.
372  	 * Therefore, the rowprep should only store the estimator in this callback.
373  	 * If the value of the estimator in the solution is smaller (larger) than `targetvalue`
374  	 * when underestimating (overestimating), then no estimator needs to be computed.
375  	 * Note, that `targetvalue` can be infinite if any estimator will be accepted.
376  	 * If successful, it shall store the estimators in the given `rowpreps` data structure and set the
377  	 * `rowprep->local` flag accordingly (SCIProwprepSetLocal()).
378  	 * The sidetype of a rowprep must be set to \ref SCIP_SIDETYPE_LEFT if overestimating and
379  	 * \ref SCIP_SIDETYPE_RIGHT if underestimating.
380  	 *
381  	 * If the callback is required to indicate for which expression a reduction in the local bounds (usually by branching)
382  	 * would improve the estimator, it shall do so via calls to SCIPaddExprsViolScoreNonlinear().
383  	 *
384  	 * \param[in] scip               SCIP main data structure
385  	 * \param[in] conshdlr           constraint handler
386  	 * \param[in] nlhdlr             nonlinear handler
387  	 * \param[in] expr               expression
388  	 * \param[in] nlhdlrexprdata     expression data of nonlinear handler
389  	 * \param[in] sol                solution at which to estimate (NULL for the LP solution)
390  	 * \param[in] auxvalue           current value of expression w.r.t. auxiliary variables as obtained from \ref SCIP_DECL_NLHDLREVALAUX "EVALAUX"
391  	 * \param[in] overestimate       whether the expression needs to be over- or underestimated
392  	 * \param[in] targetvalue        a value the estimator shall exceed, can be +/-infinity
393  	 * \param[in] addbranchscores    indicates whether to register branching scores
394  	 * \param[out] rowpreps          an array where to store the estimators
395  	 * \param[out] success           buffer to indicate whether an estimator could be computed
396  	 * \param[out] addedbranchscores buffer to store whether the branching score callback was successful
397  	 */
398  	#define SCIP_DECL_NLHDLRESTIMATE(x) SCIP_RETCODE x (\
399  	   SCIP*                scip,            \
400  	   SCIP_CONSHDLR*       conshdlr,        \
401  	   SCIP_NLHDLR*         nlhdlr,          \
402  	   SCIP_EXPR*           expr,            \
403  	   SCIP_NLHDLREXPRDATA* nlhdlrexprdata,  \
404  	   SCIP_SOL*            sol,             \
405  	   SCIP_Real            auxvalue,        \
406  	   SCIP_Bool            overestimate,    \
407  	   SCIP_Real            targetvalue,     \
408  	   SCIP_Bool            addbranchscores, \
409  	   SCIP_PTRARRAY*       rowpreps,        \
410  	   SCIP_Bool*           success,         \
411  	   SCIP_Bool*           addedbranchscores)
412  	
413  	/** nonlinear handler solution linearization callback
414  	 *
415  	 * The callback is called when a new feasible solution has been found.
416  	 * The nonlinear handler may add tight estimates on its nonlinear function to the cut pool of SCIP.
417  	 *
418  	 * \param[in] scip               SCIP main data structure
419  	 * \param[in] conshdlr           constraint handler
420  	 * \param[in] cons               a nonlinear constraint which includes expression
421  	 * \param[in] nlhdlr             nonlinear handler
422  	 * \param[in] expr               expression
423  	 * \param[in] nlhdlrexprdata     expression data of nonlinear handler
424  	 * \param[in] sol                solution that has been found
425  	 * \param[in] solisbest          whether solution is new best solution (incumbent)
426  	 * \param[in] overestimate       whether the expression needs is overestimated by the nlhdlr
427  	 * \param[in] underestimate      whether the expression needs is underestimated by the nlhdlr
428  	 */
429  	#define SCIP_DECL_NLHDLRSOLLINEARIZE(x) SCIP_RETCODE x (\
430  	   SCIP*                scip,            \
431  	   SCIP_CONSHDLR*       conshdlr,        \
432  	   SCIP_CONS*           cons,            \
433  	   SCIP_NLHDLR*         nlhdlr,          \
434  	   SCIP_EXPR*           expr,            \
435  	   SCIP_NLHDLREXPRDATA* nlhdlrexprdata,  \
436  	   SCIP_SOL*            sol,             \
437  	   SCIP_Bool            solisbest,       \
438  	   SCIP_Bool            overestimate,    \
439  	   SCIP_Bool            underestimate)
440  	
441  	typedef struct SCIP_Nlhdlr         SCIP_NLHDLR;          /**< nonlinear handler */
442  	typedef struct SCIP_NlhdlrData     SCIP_NLHDLRDATA;      /**< nonlinear handler data */
443  	typedef struct SCIP_NlhdlrExprData SCIP_NLHDLREXPRDATA;  /**< nonlinear handler data for a specific expression */
444  	
445  	#endif /* SCIP_TYPE_NLHDLR_H_ */
446