Go to the documentation of this file.
46 #include "scip/type_expr.h"
47 #include "scip/type_cons.h"
48 #include "scip/type_misc.h"
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 */
70 #define SCIP_DECL_NLHDLRCOPYHDLR(x) SCIP_RETCODE x (\
82 #define SCIP_DECL_NLHDLRFREEHDLRDATA(x) SCIP_RETCODE x (\
94 #define SCIP_DECL_NLHDLRFREEEXPRDATA(x) SCIP_RETCODE x (\
105 #define SCIP_DECL_NLHDLRINIT(x) SCIP_RETCODE x (\
114 #define SCIP_DECL_NLHDLREXIT(x) SCIP_RETCODE x (\
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
123 * For linear under- or overestimation and cut generation, an auxiliary variable (`auxvar`) can be assumed to
127 * - \ref SCIP_NLHDLR_METHOD_SEPABELOW : linear underestimation of `expr` or cut generation for the relation `expr` ≤ `auxvar` (denoted as "below")
128 * - \ref SCIP_NLHDLR_METHOD_SEPAABOVE : linear overestimation of `expr` or cut generation for the relation `expr` ≥ `auxvar` (denoted as "above")
129 * - \ref SCIP_NLHDLR_METHOD_ACTIVITY : domain propagation (i.e., constant under/overestimation) for the relation `expr` = `auxvar`.
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` ≥ `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.)
138 * The DETECT callback shall augment the `enforcing` bitmask by setting the enforcement methods it wants to provide in an "enforcement" sense.
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
143 * This can be useful for nonlinear handlers that do not implement a complete enforcement, e.g., a handler that only contributes
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
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.
154 * If \ref SCIP_NLHDLR_METHOD_ACTIVITY has been set, then at least one of \ref SCIP_DECL_NLHDLRINTEVAL "INTEVAL" and
156 * If the nonlinear handler chooses not to participate, then it must not set `nlhdlrexprdata` and can leave `participating` at its
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",
163 * - it will use activity for some subexpressions when in \ref SCIP_DECL_NLHDLRINTEVAL "INTEVAL" or \ref SCIP_DECL_NLHDLRREVERSEPROP "REVERSEPROP".
165 * @note Auxiliary variables do not exist in subexpressions during DETECT and are not created by a call to @ref SCIPregisterExprUsageNonlinear().
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
177 #define SCIP_DECL_NLHDLRDETECT(x) SCIP_RETCODE x (\
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.
202 #define SCIP_DECL_NLHDLREVALAUX(x) SCIP_RETCODE x (\
218 * \param[in,out] interval buffer where to store interval (on input: current interval for expr, on output: computed interval for expr)
222 #define SCIP_DECL_NLHDLRINTEVAL(x) SCIP_RETCODE x (\
234 * The arguments of an expression are other expressions and the tighter intervals should be passed
243 * \param[out] infeasible buffer to store whether an expression's bounds were propagated to an empty interval
246 #define SCIP_DECL_NLHDLRREVERSEPROP(x) SCIP_RETCODE x (\
258 * The method shall initialize the separation data of the nonlinear handler, if any, and add initial cuts to the LP relaxation.
268 * \param[out] infeasible buffer to store whether infeasibility was detected while building the LP
270 #define SCIP_DECL_NLHDLRINITSEPA(x) SCIP_RETCODE x (\
290 #define SCIP_DECL_NLHDLREXITSEPA(x) SCIP_RETCODE x (\
310 * - bound tightening, i.e., changing bounds on a variable so that the given point is outside the updated domain,
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.
318 * Note, that the nonlinear handler may also choose to separate for a relaxation of the mentioned sets,
322 * cons_nonlinear ensures that `lhs` ≤ lowerbound(`auxvar`) and upperbound(`auxvar`) ≤ `rhs`.
324 * cons_nonlinear may call this callback first with `allowweakcuts` = FALSE and repeat later with
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.
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.
346 * \param[in] auxvalue current value of expression w.r.t. auxiliary variables as obtained from \ref SCIP_DECL_NLHDLREVALAUX "EVALAUX"
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
353 #define SCIP_DECL_NLHDLRENFO(x) SCIP_RETCODE x (\
370 * The method tries to compute linear under- or overestimators of `expr` that are as tight as possible at a given point.
374 * If successful, it shall store the estimators in the given `rowpreps` data structure and set the
379 * If the callback is required to indicate for which expression a reduction in the local bounds (usually by branching)
388 * \param[in] auxvalue current value of expression w.r.t. auxiliary variables as obtained from \ref SCIP_DECL_NLHDLREVALAUX "EVALAUX"
394 * \param[out] addedbranchscores buffer to store whether the branching score callback was successful
396 #define SCIP_DECL_NLHDLRESTIMATE(x) SCIP_RETCODE x (\
413 typedef struct SCIP_NlhdlrExprData SCIP_NLHDLREXPRDATA; /**< nonlinear handler data for a specific expression */
type definitions for miscellaneous datastructures
type and macro definitions related to algebraic expressions
type definitions for constraints and constraint handlers