type_nlhdlr.h
Go to the documentation of this file.
42 #define SCIP_NLHDLR_METHOD_SEPABELOW 0x1u /**< separation for expr <= auxvar, thus might estimate expr from below */
43 #define SCIP_NLHDLR_METHOD_SEPAABOVE 0x2u /**< separation for expr >= auxvar, thus might estimate expr from above */
44 #define SCIP_NLHDLR_METHOD_SEPABOTH (SCIP_NLHDLR_METHOD_SEPABELOW | SCIP_NLHDLR_METHOD_SEPAABOVE) /**< separation for expr == auxvar */
45 #define SCIP_NLHDLR_METHOD_ACTIVITY 0x4u /**< activity computation (interval evaluation) and propagation (reverse propagation) */
46 #define SCIP_NLHDLR_METHOD_ALL (SCIP_NLHDLR_METHOD_SEPABOTH | SCIP_NLHDLR_METHOD_ACTIVITY) /**< all enforcement methods */
111 * The nonlinear handler shall analyze the current expression and decide whether it wants to contribute
112 * in enforcing the relation between this expression (`expr`) and its descendants (e.g., children) via
114 * For linear under- or overestimation and cut generation, an auxiliary variable (`auxvar`) can be assumed to
118 * - \ref SCIP_NLHDLR_METHOD_SEPABELOW : linear underestimation of `expr` or cut generation for the relation `expr` ≤ `auxvar` (denoted as "below")
119 * - \ref SCIP_NLHDLR_METHOD_SEPAABOVE : linear overestimation of `expr` or cut generation for the relation `expr` ≥ `auxvar` (denoted as "above")
120 * - \ref SCIP_NLHDLR_METHOD_ACTIVITY : domain propagation (i.e., constant under/overestimation) for the relation `expr` = `auxvar`.
123 * - 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,
124 * or because analysis of the expression has shown that a relation like `expr` ≥ `auxvar` is not necessary to be satisfied,
125 * - or there already exists a nonlinear handler that will provide this method in an "enforcement" sense, that is,
126 * it believes that no one else could provide this method in a stronger sense. (This is mainly used by nlhdlr_default to check whether
127 * it should still reach out to the exprhdlr or whether it would be dominated by some nonlinear handler.)
129 * The DETECT callback shall augment the `enforcing` bitmask by setting the enforcement methods it wants to provide in an "enforcement" sense.
131 * Additionally, the `participating` bitmask shall be set if the nonlinear handler wants to be called on this expression at all.
132 * Here, it shall set all methods that it wants to provide, which are those set in `enforcing`, but additionally those where it wants
134 * This can be useful for nonlinear handlers that do not implement a complete enforcement, e.g., a handler that only contributes
137 * A nonlinear handler will be called only for those callbacks that it mentioned in `participating`, which is
138 * - \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
139 * - \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
140 * - \ref SCIP_DECL_NLHDLRINTEVAL "INTEVAL" and/or \ref SCIP_DECL_NLHDLRREVERSEPROP "REVERSEPROP" will be called if \ref SCIP_NLHDLR_METHOD_ACTIVITY has been set
142 * If \ref SCIP_NLHDLR_METHOD_SEPABELOW or \ref SCIP_NLHDLR_METHOD_SEPAABOVE has been set, then at least one of the
143 * callbacks \ref SCIP_DECL_NLHDLRENFO "ENFO" and \ref SCIP_DECL_NLHDLRESTIMATE "ESTIMATE" needs to be implemented.
145 * If \ref SCIP_NLHDLR_METHOD_ACTIVITY has been set, then at least one of \ref SCIP_DECL_NLHDLRINTEVAL "INTEVAL" and
147 * If the nonlinear handler chooses not to participate, then it must not set `nlhdlrexprdata` and can leave `participating` at its
150 * Additionally, a nonlinear handler that decides to participate in any of the enforcement methods must call
151 * @ref SCIPregisterExprUsageNonlinear() for every subexpression that it will use and indicate whether
152 * - it will use an auxiliary variable in \ref SCIP_DECL_NLHDLRENFO "ENFO" or \ref SCIP_DECL_NLHDLRESTIMATE "ESTIMATE",
154 * - it will use activity for some subexpressions when in \ref SCIP_DECL_NLHDLRINTEVAL "INTEVAL" or \ref SCIP_DECL_NLHDLRREVERSEPROP "REVERSEPROP".
156 * @note Auxiliary variables do not exist in subexpressions during DETECT and are not created by a call to @ref SCIPregisterExprUsageNonlinear().
163 * \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
164 * \param[in,out] enforcing enforcement methods that are provided by some nonlinear handler (to be updated by detect callback)
165 * \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
166 * \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
180 * Evaluates the expression w.r.t. the auxiliary variables that were introduced by the nonlinear handler (if any).
181 * The method is used to determine the violation of the relation that the nonlinear handler attempts to enforce.
182 * During enforcement, this violation value is used to decide whether estimation/separation callbacks should be called.
209 * \param[in,out] interval buffer where to store interval (on input: current interval for expr, on output: computed interval for expr)
225 * The arguments of an expression are other expressions and the tighter intervals should be passed
234 * \param[out] infeasible buffer to store whether an expression's bounds were propagated to an empty interval
249 * The method shall initialize the separation data of the nonlinear handler, if any, and add initial cuts to the LP relaxation.
259 * \param[out] infeasible buffer to store whether infeasibility was detected while building the LP
301 * - bound tightening, i.e., changing bounds on a variable so that the given point is outside the updated domain,
306 * If the nonlinear handler always separates by computing a linear under- or overestimator of expr,
307 * then it could be advantageous to implement the \ref SCIP_DECL_NLHDLRESTIMATE "ESTIMATE" callback instead.
309 * Note, that the nonlinear handler may also choose to separate for a relaxation of the mentioned sets,
313 * cons_nonlinear ensures that `lhs` ≤ lowerbound(`auxvar`) and upperbound(`auxvar`) ≤ `rhs`.
315 * cons_nonlinear may call this callback first with `allowweakcuts` = FALSE and repeat later with
317 * If in enforcement and the nonlinear handler cannot enforce by separation or bound tightening, it should register
318 * branching scores for those expressions where branching may help to compute tighter cuts in children.
326 * Note that `expr` does not need to be the root of this constraint, i.e., `SCIPgetExprNonlinear(cons)==expr` may not hold.
327 * If an expression appears in several constraints, it is not well defined which constraint is given in `cons`.
328 * The main purpose of `cons` is to provide a constraint source for LP rows that are added in this callback.
337 * \param[in] auxvalue current value of expression w.r.t. auxiliary variables as obtained from \ref SCIP_DECL_NLHDLREVALAUX "EVALAUX"
339 * \param[in] allowweakcuts whether we should only look for "strong" cuts, or anything that separates is fine
340 * \param[in] separated whether another nonlinear handler already added a cut for this expression
361 * The method tries to compute linear under- or overestimators of `expr` that are as tight as possible at a given point.
365 * If successful, it shall store the estimators in the given `rowpreps` data structure and set the
370 * If the callback is required to indicate for which expression a reduction in the local bounds (usually by branching)
379 * \param[in] auxvalue current value of expression w.r.t. auxiliary variables as obtained from \ref SCIP_DECL_NLHDLREVALAUX "EVALAUX"
385 * \param[out] addedbranchscores buffer to store whether the branching score callback was successful
404 typedef struct SCIP_NlhdlrExprData SCIP_NLHDLREXPRDATA; /**< nonlinear handler data for a specific expression */
type definitions for miscellaneous datastructures
Definition: struct_nlhdlr.h:34
type and macro definitions related to algebraic expressions
type definitions for constraints and constraint handlers