Scippy

    SCIP

    Solving Constraint Integer Programs

    type_expr.h
    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/* Copyright (c) 2002-2025 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_expr.h
    26 * @ingroup TYPEDEFINITIONS
    27 * @brief type and macro definitions related to algebraic expressions
    28 * @author Ksenia Bestuzheva
    29 * @author Benjamin Mueller
    30 * @author Felipe Serrano
    31 * @author Stefan Vigerske
    32 *
    33 * This file defines the interface for expression handlers.
    34 *
    35 * - \ref EXPRHDLRS "List of available expression handlers"
    36 */
    37
    38/** @defgroup DEFPLUGINS_EXPR Default expression handlers
    39 * @ingroup DEFPLUGINS
    40 * @brief implementation files (.c files) of the default expression handlers of SCIP
    41 */
    42
    43#ifndef SCIP_TYPE_EXPR_H_
    44#define SCIP_TYPE_EXPR_H_
    45
    46#include "scip/def.h"
    47#include "scip/intervalarith.h"
    48#include "scip/type_scip.h"
    49#include "scip/type_sol.h"
    50#include "scip/type_var.h"
    51#include "scip/type_tree.h"
    52#include "scip/type_retcode.h"
    53
    54typedef struct SCIP_ExprData SCIP_EXPRDATA; /**< expression data, e.g., coefficients */
    55typedef struct SCIP_Expr SCIP_EXPR; /**< expression */
    56typedef struct SYM_ExprData SYM_EXPRDATA; /**< (additional) data used to encode an expression,
    57 * which is not encoded as another expression */
    58
    59/** curvature types */
    60typedef enum
    61{
    62 SCIP_EXPRCURV_UNKNOWN = 0, /**< unknown or indefinite curvature */
    63 SCIP_EXPRCURV_CONVEX = 1, /**< convex */
    64 SCIP_EXPRCURV_CONCAVE = 2, /**< concave */
    65 SCIP_EXPRCURV_LINEAR = SCIP_EXPRCURV_CONVEX | SCIP_EXPRCURV_CONCAVE/**< linear = convex and concave */
    67
    68/** monotonicity */
    69typedef enum
    70{
    71 SCIP_MONOTONE_UNKNOWN = 0, /**< unknown or non-monotone */
    72 SCIP_MONOTONE_INC = 1, /**< increasing */
    73 SCIP_MONOTONE_DEC = 2, /**< decreasing */
    74 SCIP_MONOTONE_CONST = SCIP_MONOTONE_INC | SCIP_MONOTONE_DEC /**< constant = increasing and decreasing */
    76
    77/**@name Expression Owner */
    78/**@{ */
    79
    80typedef struct SCIP_Expr_OwnerData SCIP_EXPR_OWNERDATA; /**< data stored by expression owner (e.g., conshdlr, nlp) in expression */
    81
    82/** callback for freeing ownerdata of expression
    83 *
    84 * This callback is called while an expression is freed.
    85 * The callback shall free the ownerdata, if any.
    86 * That is, the callback is also called on expressions that only store this callback, but no ownerdata.
    87 *
    88 * Note, that the children of the expression have already been released when this callback is called.
    89 * The callback must not try to access the expressions children.
    90 *
    91 * \param[in] scip SCIP main data structure
    92 * \param[in] expr the expression which is freed
    93 * \param[in] ownerdata the ownerdata stored in the expression
    94 */
    95#define SCIP_DECL_EXPR_OWNERFREE(x) SCIP_RETCODE x(\
    96 SCIP* scip, \
    97 SCIP_EXPR* expr, \
    98 SCIP_EXPR_OWNERDATA** ownerdata)
    99
    100/** callback for printing ownerdata of expression
    101 *
    102 * This callback is called when printing details on an expression, e.g., SCIPdismantleExpr().
    103 *
    104 * \param[in] scip SCIP main data structure
    105 * \param[in] expr the expression which is printed
    106 * \param[in] file file to print to, or NULL for stdout
    107 * \param[in] ownerdata the ownerdata stored in the expression
    108 */
    109#define SCIP_DECL_EXPR_OWNERPRINT(x) SCIP_RETCODE x(\
    110 SCIP* scip, \
    111 FILE* file, \
    112 SCIP_EXPR* expr, \
    113 SCIP_EXPR_OWNERDATA* ownerdata)
    114
    115/** callback for owner-specific activity evaluation
    116 *
    117 * This callback is called when evaluating the activity of an expression, e.g., SCIPevalActivity().
    118 * The callback should ensure that activity is updated, if required, by calling SCIPsetActivity().
    119 * The callback can use the activitytag in the expression to recognize whether it needs to become active.
    120 *
    121 * \param[in] scip SCIP main data structure
    122 * \param[in] expr the expression for which activity should be updated
    123 * \param[in] ownerdata the ownerdata stored in the expression
    124 */
    125#define SCIP_DECL_EXPR_OWNEREVALACTIVITY(x) SCIP_RETCODE x(\
    126 SCIP* scip, \
    127 SCIP_EXPR* expr, \
    128 SCIP_EXPR_OWNERDATA* ownerdata)
    129
    130/** callback for creating ownerdata of expression
    131 *
    132 * This callback is called when an expression has been created.
    133 * It can create data which is then stored in the expression.
    134 *
    135 * \param[in] scip SCIP main data structure
    136 * \param[in] expr the expression that has been created
    137 * \param[out] ownerdata buffer to store ownerdata that shall be stored in expression (can be NULL, initialized to NULL)
    138 * \param[out] ownerfree buffer to store function to be called to free ownerdata when expression is freed (can be NULL, initialized to NULL)
    139 * \param[out] ownerprint buffer to store function to be called to print ownerdata (can be NULL, initialized to NULL)
    140 * \param[out] ownerevalactivity buffer to store function to be called to evaluate activity (can be NULL, initialized to NULL)
    141 * \param[in] ownercreatedata data that has been passed on by future owner of expression that can be used to create ownerdata
    142 */
    143#define SCIP_DECL_EXPR_OWNERCREATE(x) SCIP_RETCODE x(\
    144 SCIP* scip, \
    145 SCIP_EXPR* expr, \
    146 SCIP_EXPR_OWNERDATA** ownerdata, \
    147 SCIP_DECL_EXPR_OWNERFREE((**ownerfree)), \
    148 SCIP_DECL_EXPR_OWNERPRINT((**ownerprint)), \
    149 SCIP_DECL_EXPR_OWNEREVALACTIVITY((**ownerevalactivity)), \
    150 void* ownercreatedata)
    151
    152/** @} */ /* expression owner */
    153
    154/** callback that returns bounds for a given variable as used in interval evaluation
    155 *
    156 * Implements a relaxation scheme for variable bounds and translates between different infinity values.
    157 * Returns an interval that contains the current variable bounds, but might be (slightly) larger.
    158 *
    159 * \param[in] scip SCIP main data structure
    160 * \param[in] var variable for which to obtain bounds
    161 * \param[in] intevalvardata data that belongs to this callback
    162 */
    163#define SCIP_DECL_EXPR_INTEVALVAR(x) SCIP_INTERVAL x (\
    164 SCIP* scip, \
    165 SCIP_VAR* var, \
    166 void* intevalvardata \
    167 )
    168
    169/** expression mapping callback for expression copy callback
    170 *
    171 * The method maps an expression (in a source SCIP instance) to an expression
    172 * (in a target SCIP instance) and captures the target expression.
    173 *
    174 * \param[in] targetscip target SCIP main data structure
    175 * \param[out] targetexpr pointer to store the mapped expression, or NULL if expression shall be copied; initialized to NULL
    176 * \param[in] sourcescip source SCIP main data structure
    177 * \param[in] sourceexpr expression to be mapped
    178 * \param[in] ownercreate callback to call when creating a new expression
    179 * \param[in] ownercreatedata data for ownercreate callback
    180 * \param[in] mapexprdata data of mapexpr callback
    181 */
    182#define SCIP_DECL_EXPR_MAPEXPR(x) SCIP_RETCODE x (\
    183 SCIP* targetscip, \
    184 SCIP_EXPR** targetexpr, \
    185 SCIP* sourcescip, \
    186 SCIP_EXPR* sourceexpr, \
    187 SCIP_DECL_EXPR_OWNERCREATE((*ownercreate)), \
    188 void* ownercreatedata, \
    189 void* mapexprdata)
    190
    191/**@name Expression Handler */
    192/**@{ */
    193
    194typedef struct SCIP_Exprhdlr SCIP_EXPRHDLR; /**< expression handler */
    195typedef struct SCIP_ExprhdlrData SCIP_EXPRHDLRDATA; /**< expression handler data, e.g., SCIP parameter values */
    196
    197/** the maximal number of estimates an expression handler can return in the INITESTIMATES callback */
    198#define SCIP_EXPR_MAXINITESTIMATES 10
    199
    200/** expression handler copy callback
    201 *
    202 * The method should include the expression handler into a given SCIP instance.
    203 * It is usually called when doing a copy of SCIP.
    204 *
    205 * \param[in] scip target SCIP main data structure where to include expression handler
    206 * \param[in] sourceexprhdlr expression handler in source SCIP
    207 *
    208 * See also \ref EXPRCOPYHDLR.
    209 */
    210#define SCIP_DECL_EXPRCOPYHDLR(x) SCIP_RETCODE x (\
    211 SCIP* scip, \
    212 SCIP_EXPRHDLR* sourceexprhdlr)
    213
    214/** expression handler free callback
    215 *
    216 * Frees the data of an expression handler.
    217 *
    218 * \param[in] scip SCIP main data structure
    219 * \param[in] exprhdlr expression handler
    220 * \param[in] exprhdlrdata expression handler data to be freed
    221 *
    222 * See also \ref EXPRFREEHDLR.
    223 */
    224#define SCIP_DECL_EXPRFREEHDLR(x) SCIP_RETCODE x (\
    225 SCIP* scip, \
    226 SCIP_EXPRHDLR* exprhdlr, \
    227 SCIP_EXPRHDLRDATA** exprhdlrdata)
    228
    229/** expression data copy callback
    230 *
    231 * Copies the data of an expression.
    232 *
    233 * This method is called when creating copies of an expression within
    234 * the same or between different SCIP instances. It is given the
    235 * source expression, which data shall be copied. It expects
    236 * that *targetexprdata will be set. This data will then be used
    237 * to create a new expression.
    238 *
    239 * This callback must be implemented for expressions that have data.
    240 *
    241 * \param[in] targetscip target SCIP main data structure
    242 * \param[in] targetexprhdlr expression handler in target SCIP
    243 * \param[out] targetexprdata pointer to store the copied expression data
    244 * \param[in] sourcescip source SCIP main data structure
    245 * \param[in] sourceexpr expression in source SCIP which data is to be copied
    246 *
    247 * See also \ref EXPRCOPYDATA.
    248 */
    249#define SCIP_DECL_EXPRCOPYDATA(x) SCIP_RETCODE x (\
    250 SCIP* targetscip, \
    251 SCIP_EXPRHDLR* targetexprhdlr, \
    252 SCIP_EXPRDATA** targetexprdata, \
    253 SCIP* sourcescip, \
    254 SCIP_EXPR* sourceexpr)
    255
    256/** expression data free callback
    257 *
    258 * Frees the data of an expression.
    259 * Shall call SCIPexprSetData(expr, NULL).
    260 *
    261 * This callback must be implemented for expressions that have data.
    262 *
    263 * \param[in] scip SCIP main data structure
    264 * \param[in] expr the expression which data to be freed
    265 *
    266 * See also \ref EXPRFREEDATA.
    267 */
    268#define SCIP_DECL_EXPRFREEDATA(x) SCIP_RETCODE x (\
    269 SCIP* scip, \
    270 SCIP_EXPR* expr)
    271
    272/** expression print callback
    273 *
    274 * Prints an expression.
    275 * It is called while DFS-iterating over the expression at different stages, that is,
    276 * when the expression is visited the first time, before each child of the expression is visited,
    277 * after each child of the expression has been visited, and when the iterator leaves the expression
    278 * for its parent. See also \ref SCIP_EXPRITER_DFS "expression iteration docu".
    279 *
    280 * \param[in] scip SCIP main data structure
    281 * \param[in] expr expression which data is to be printed
    282 * \param[in] stage stage of expression iteration
    283 * \param[in] currentchild index of current child if in stage visitingchild or visitedchild
    284 * \param[in] parentprecedence precedence of parent
    285 * \param[in] file the file to print to
    286 *
    287 * See also \ref EXPRPRINT.
    288 */
    289#define SCIP_DECL_EXPRPRINT(x) SCIP_RETCODE x (\
    290 SCIP* scip, \
    291 SCIP_EXPR* expr, \
    292 SCIP_EXPRITER_STAGE stage, \
    293 int currentchild, \
    294 unsigned int parentprecedence, \
    295 FILE* file)
    296
    297/** expression parse callback
    298 *
    299 * Parses an expression.
    300 * It is called when parsing an expression and an operator with the expr handler name is found.
    301 *
    302 * \param[in] scip SCIP main data structure
    303 * \param[in] string string containing expression to be parse
    304 * \param[in] ownercreate function to call to create ownerdata
    305 * \param[in] ownercreatedata data to pass to ownercreate
    306 * \param[out] endstring buffer to store the position of string after parsing
    307 * \param[out] expr buffer to store the parsed expression
    308 * \param[out] success buffer to store whether the parsing was successful or not
    309 *
    310 * See also \ref EXPRPARSE.
    311 */
    312#define SCIP_DECL_EXPRPARSE(x) SCIP_RETCODE x (\
    313 SCIP* scip, \
    314 SCIP_EXPRHDLR* exprhdlr, \
    315 const char* string, \
    316 const char** endstring, \
    317 SCIP_EXPR** expr, \
    318 SCIP_Bool* success, \
    319 SCIP_DECL_EXPR_OWNERCREATE((*ownercreate)), \
    320 void* ownercreatedata)
    321
    322/** expression curvature detection callback
    323 *
    324 * The method returns whether an expression can have a desired curvature under conditions on the
    325 * curvature of the children.
    326 * That is, the method shall return TRUE in success and requirements on the curvature for each child
    327 * which will suffice for this expression to be convex (or concave, or linear, as specified by caller)
    328 * w.r.t. the current activities of all children.
    329 * It can return "unknown" for a child's curvature if its curvature does not matter (though that's
    330 * rarely the case).
    331 *
    332 * \param[in] scip SCIP main data structure
    333 * \param[in] expr expression to check the curvature for
    334 * \param[in] exprcurvature desired curvature of this expression
    335 * \param[out] success buffer to store whether the desired curvature was obtained
    336 * \param[out] childcurv array to store required curvature for each child
    337 *
    338 * See also \ref EXPRCURVATURE.
    339 */
    340#define SCIP_DECL_EXPRCURVATURE(x) SCIP_RETCODE x (\
    341 SCIP* scip, \
    342 SCIP_EXPR* expr, \
    343 SCIP_EXPRCURV exprcurvature, \
    344 SCIP_Bool* success, \
    345 SCIP_EXPRCURV* childcurv)
    346
    347/** expression monotonicity detection callback
    348 *
    349 * The method computes the monotonicity of an expression with respect to a given child.
    350 *
    351 * \param[in] scip SCIP main data structure
    352 * \param[in] expr expression to check the monotonicity for
    353 * \param[in] childidx index of the considered child expression
    354 * \param[out] result buffer to store the monotonicity
    355 *
    356 * See also \ref EXPRMONOTONICITY.
    357 */
    358#define SCIP_DECL_EXPRMONOTONICITY(x) SCIP_RETCODE x (\
    359 SCIP* scip, \
    360 SCIP_EXPR* expr, \
    361 int childidx, \
    362 SCIP_MONOTONE* result)
    363
    364/** expression integrality detection callback
    365 *
    366 * The method computes the integrality of an expression.
    367 * The integrality of an expression f(y) is defined as the implied integer type of an auxiliary continuous variable x
    368 * that is introduced such that x = f(y) holds. Usually uses SCIPexprGetIntegrality() or SCIPexprIsIntegral() to get the
    369 * integrality of children expressions.
    370 *
    371 * \param[in] scip SCIP main data structure
    372 * \param[in] expr expression to check the integrality for
    373 * \param[out] integrality buffer to store the integrality of the expression
    374 *
    375 * See also \ref EXPRINTEGRALITY.
    376 */
    377#define SCIP_DECL_EXPRINTEGRALITY(x) SCIP_RETCODE x (\
    378 SCIP* scip, \
    379 SCIP_EXPR* expr, \
    380 SCIP_IMPLINTTYPE* integrality)
    381
    382/** expression hash callback
    383 *
    384 * The method hashes an expression by taking the hashes of its children into account.
    385 *
    386 * \param[in] scip SCIP main data structure
    387 * \param[in] expr expression to be hashed
    388 * \param[out] hashkey buffer to store the hash value
    389 * \param[in] childrenhashes array with hash values of children
    390 *
    391 * See also \ref EXPRHASH.
    392 */
    393#define SCIP_DECL_EXPRHASH(x) SCIP_RETCODE x (\
    394 SCIP* scip, \
    395 SCIP_EXPR* expr, \
    396 unsigned int* hashkey, \
    397 unsigned int* childrenhashes)
    398
    399/** expression compare callback
    400 *
    401 * the method receives two expressions, expr1 and expr2. Must return
    402 * -1 if expr1 < expr2, or
    403 * 0 if expr1 = expr2, or
    404 * 1 if expr1 > expr2.
    405 *
    406 * \param[in] scip SCIP main data structure
    407 * \param[in] expr1 first expression in comparison
    408 * \param[in] expr2 second expression in comparison
    409 *
    410 * See also \ref EXPRCOMPARE.
    411 */
    412#define SCIP_DECL_EXPRCOMPARE(x) int x (\
    413 SCIP* scip, \
    414 SCIP_EXPR* expr1, \
    415 SCIP_EXPR* expr2)
    416
    417/** expression (point-) evaluation callback
    418 *
    419 * The method evaluates an expression by taking the values of its children into account.
    420 *
    421 * \param[in] scip SCIP main data structure
    422 * \param[in] expr expression to be evaluated
    423 * \param[out] val buffer where to store value
    424 * \param[in] sol solution that is evaluated (can be NULL)
    425 *
    426 * See also \ref EXPREVAL.
    427 */
    428#define SCIP_DECL_EXPREVAL(x) SCIP_RETCODE x (\
    429 SCIP* scip, \
    430 SCIP_EXPR* expr, \
    431 SCIP_Real* val, \
    432 SCIP_SOL* sol)
    433
    434/** backward derivative evaluation callback
    435 *
    436 * The method should compute the partial derivative of expr w.r.t. its child at childidx.
    437 * That is, it should return
    438 * \f[
    439 * \frac{\partial \text{expr}}{\partial \text{child}_{\text{childidx}}}
    440 * \f]
    441 *
    442 * See \ref SCIP_EXPR_DIFF "Differentiation methods in scip_expr.h" for more details.
    443 *
    444 * \param[in] scip SCIP main data structure
    445 * \param[in] expr expression to be differentiated
    446 * \param[in] childidx index of the child
    447 * \param[out] val buffer to store the partial derivative w.r.t. the childidx-th children
    448 *
    449 * See also \ref EXPRBWDIFF.
    450 */
    451#define SCIP_DECL_EXPRBWDIFF(x) SCIP_RETCODE x (\
    452 SCIP* scip, \
    453 SCIP_EXPR* expr, \
    454 int childidx, \
    455 SCIP_Real* val)
    456
    457/** forward derivative evaluation callback
    458 *
    459 * The method should evaluate the directional derivative of expr.
    460 * The expr should be interpreted as an operator \f$ \text{expr}(c_1, \ldots, c_n) \f$, where \f$ c_1, \ldots, c_n \f$
    461 * are the children of the expr.
    462 * The directional derivative is evaluated at the point
    463 * SCIPexprGetEvalValue\f$(c_1)\f$, ..., SCIPexprGetEvalValue\f$(c_n)\f$
    464 * in the direction given by direction.
    465 *
    466 * This method should return
    467 * \f[
    468 * \sum_{i = 1}^n \frac{\partial \text{expr}}{\partial c_i} D_u c_i,
    469 * \f]
    470 * where \f$ u \f$ is the direction and \f$ D_u c_i \f$ is the directional derivative of the i-th child,
    471 * which can be accessed via SCIPexprGetDot().
    472 *
    473 * See \ref SCIP_EXPR_DIFF "Differentiation methods in scip_expr.h" for more details.
    474 *
    475 * \param[in] scip SCIP main data structure
    476 * \param[in] expr expression to be differentiated
    477 * \param[out] dot buffer to store derivative value
    478 * \param[in] direction direction of the derivative (useful only for var expressions)
    479 *
    480 * See also \ref EXPRFWDIFF.
    481 */
    482#define SCIP_DECL_EXPRFWDIFF(x) SCIP_RETCODE x (\
    483 SCIP* scip, \
    484 SCIP_EXPR* expr, \
    485 SCIP_Real* dot, \
    486 SCIP_SOL* direction)
    487
    488/** derivative evaluation callback for Hessian directions (backward over forward)
    489 *
    490 * The method computes the total derivative, w.r.t. its children, of the partial derivative of expr w.r.t. childidx.
    491 * Equivalently, it computes the partial derivative w.r.t. childidx of the total derivative.
    492 *
    493 * The expr should be interpreted as an operator \f$ \text{expr}(c_1, \ldots, c_n) \f$, where \f$ c_1, \ldots, c_n \f$
    494 * are the children of the expr.
    495 * The directional derivative is evaluated at the point
    496 * SCIPexprGetEvalValue\f$(c_1)\f$, ..., SCIPexprGetEvalValue\f$(c_n)\f$
    497 * in the direction given by direction.
    498 *
    499 * This method should return
    500 * \f[
    501 * \sum_{i = 1}^n \frac{\partial^2 \text{expr}}{\partial c_i} \partial c_{\text{childidx}} D_u c_i,
    502 * \f]
    503 *
    504 * where \f$ u \f$ is the direction and \f$ D_u c_i \f$ is the directional derivative of the i-th child,
    505 * which can be accessed via SCIPexprGetDot().
    506 *
    507 * Thus, if \f$ n = 1 \f$ (i.e. if expr represents an univariate operator), the method should return
    508 * \f[
    509 * \text{expr}^{\prime \prime}(\text{SCIPexprGetEvalValue}(c)) D_u c.
    510 * \f]
    511 *
    512 * See \ref SCIP_EXPR_DIFF "Differentiation methods in scip_expr.h" for more details.
    513 *
    514 * \param[in] scip SCIP main data structure
    515 * \param[in] expr expression to be evaluated
    516 * \param[in] childidx index of the child
    517 * \param[out] bardot buffer to store derivative value
    518 * \param[in] direction direction of the derivative (useful only for var expressions)
    519 *
    520 * See also \ref EXPRBWFWDIFF.
    521 */
    522#define SCIP_DECL_EXPRBWFWDIFF(x) SCIP_RETCODE x (\
    523 SCIP* scip, \
    524 SCIP_EXPR* expr, \
    525 int childidx, \
    526 SCIP_Real* bardot, \
    527 SCIP_SOL* direction)
    528
    529/** expression (interval-) evaluation callback
    530 *
    531 * The method evaluates an expression by taking the intervals of its children into account.
    532 *
    533 * \param[in] scip SCIP main data structure
    534 * \param[in] expr expression to be evaluated
    535 * \param[out] interval buffer where to store interval
    536 * \param[in] intevalvar callback to be called when interval evaluating a variable
    537 * \param[in] intevalvardata data to be passed to intevalvar callback
    538 *
    539 * See also \ref EXPRINTEVAL.
    540 */
    541#define SCIP_DECL_EXPRINTEVAL(x) SCIP_RETCODE x (\
    542 SCIP* scip, \
    543 SCIP_EXPR* expr, \
    544 SCIP_INTERVAL* interval, \
    545 SCIP_DECL_EXPR_INTEVALVAR((*intevalvar)), \
    546 void* intevalvardata)
    547
    548/** expression under/overestimation callback
    549 *
    550 * The method tries to compute a linear under- or overestimator that is as tight as possible
    551 * at a given point. The estimator must be valid w.r.t. the bounds given by localbounds.
    552 * If the value of the estimator in the reference point is smaller (larger) than targetvalue
    553 * when underestimating (overestimating), then no estimator needs to be computed.
    554 * Note, that targetvalue can be infinite if any estimator will be accepted.
    555 * If successful, it shall store the coefficient of the i-th child in entry coefs[i] and
    556 * the constant part in constant.
    557 * If the estimator is also valid w.r.t. the bounds given by globalbounds, then *islocal shall
    558 * be set to FALSE.
    559 * The callback shall indicate in branchcand[i] whether branching on the i-th child would improve
    560 * the estimator. It can be assumed that branchcand[i] has been initialized to TRUE for all children.
    561 *
    562 * \param[in] scip SCIP main data structure
    563 * \param[in] expr expression
    564 * \param[in] localbounds current bounds for children
    565 * \param[in] globalbounds global bounds for children
    566 * \param[in] refpoint values for children in the reference point where to estimate
    567 * \param[in] overestimate whether the expression needs to be over- or underestimated
    568 * \param[in] targetvalue a value that the estimator shall exceed, can be +/-infinity
    569 * \param[out] coefs array to store coefficients of estimator
    570 * \param[out] constant buffer to store constant part of estimator
    571 * \param[out] islocal buffer to store whether estimator is valid locally only
    572 * \param[out] success buffer to indicate whether an estimator could be computed
    573 * \param[out] branchcand array to indicate which children to consider for branching
    574 *
    575 * See also \ref EXPRESTIMATE.
    576 */
    577#define SCIP_DECL_EXPRESTIMATE(x) SCIP_RETCODE x (\
    578 SCIP* scip, \
    579 SCIP_EXPR* expr, \
    580 SCIP_INTERVAL* localbounds, \
    581 SCIP_INTERVAL* globalbounds, \
    582 SCIP_Real* refpoint, \
    583 SCIP_Bool overestimate, \
    584 SCIP_Real targetvalue, \
    585 SCIP_Real* coefs, \
    586 SCIP_Real* constant, \
    587 SCIP_Bool* islocal, \
    588 SCIP_Bool* success, \
    589 SCIP_Bool* branchcand)
    590
    591/** expression initial under/overestimation callback
    592 *
    593 * The method tries to compute a few linear under- or overestimator that approximate the
    594 * behavior of the expression. The estimator must be valid w.r.t. the bounds given by bounds.
    595 * These estimators may be used to initialize a linear relaxation.
    596 * The callback shall return the number of computed estimators in nreturned,
    597 * store the coefficient of the i-th child for the j-th estimator in entry coefs[j][i],
    598 * and store the constant part for the j-th estimator in constant[j].
    599 *
    600 * \param[in] scip SCIP main data structure
    601 * \param[in] expr expression
    602 * \param[in] bounds bounds for children
    603 * \param[in] overestimate whether the expression shall be overestimated or underestimated
    604 * \param[out] coefs buffer to store coefficients of computed estimators
    605 * \param[out] constant buffer to store constant of computed estimators
    606 * \param[out] nreturned buffer to store number of estimators that have been computed
    607 *
    608 * See also \ref EXPRINITESTIMATES.
    609 */
    610#define SCIP_DECL_EXPRINITESTIMATES(x) SCIP_RETCODE x ( \
    611 SCIP* scip, \
    612 SCIP_EXPR* expr, \
    613 SCIP_INTERVAL* bounds, \
    614 SCIP_Bool overestimate, \
    615 SCIP_Real* coefs[SCIP_EXPR_MAXINITESTIMATES], \
    616 SCIP_Real constant[SCIP_EXPR_MAXINITESTIMATES], \
    617 int* nreturned)
    618
    619/** expression simplify callback
    620 *
    621 * The method shall try to simplify an expression by applying algebraic transformations
    622 * and return the simplified expression.
    623 * It can assume that children have been simplified.
    624 * If no simplification is possible, then shall set *simplifiedexpr to expr and capture *simplifiedexpr.
    625 *
    626 * \param[in] scip SCIP main data structure
    627 * \param[in] expr expression to simplify
    628 * \param[in] ownercreate function to call to create ownerdata
    629 * \param[in] ownercreatedata data to pass to ownercreate
    630 * \param[out] simplifiedexpr buffer to store the simplified expression
    631 *
    632 * See also \ref EXPRSIMPLIFY and SCIPsimplifyExpr().
    633 */
    634#define SCIP_DECL_EXPRSIMPLIFY(x) SCIP_RETCODE x (\
    635 SCIP* scip, \
    636 SCIP_EXPR* expr, \
    637 SCIP_EXPR** simplifiedexpr, \
    638 SCIP_DECL_EXPR_OWNERCREATE((*ownercreate)), \
    639 void* ownercreatedata)
    640
    641/** expression callback for reverse propagation
    642 *
    643 * The method propagates given bounds over the children of an expression.
    644 * Shall compute an interval overestimate on
    645 * \f[
    646 * \{ x_i : \text{expr}(c_1,\ldots,c_{i-1},x_i,c_{i+1},\ldots,c_n) \in \text{bounds} \}
    647 * \f]
    648 * for each child i and store it in childrenbounds[i].
    649 * The initial intervals \f$c_i, i=1,\ldots,n,\f$ are given by childrenbounds, too.
    650 *
    651 * \param[in] scip SCIP main data structure
    652 * \param[in] expr expression
    653 * \param[in] bounds the bounds on the expression that should be propagated
    654 * \param[in,out] childrenbounds array to store computed bounds for children, initialized with current activity
    655 * \param[out] infeasible buffer to store whether a children bounds were propagated to an empty interval
    656 *
    657 * See also \ref EXPRREVERSEPROP.
    658 */
    659#define SCIP_DECL_EXPRREVERSEPROP(x) SCIP_RETCODE x (\
    660 SCIP* scip, \
    661 SCIP_EXPR* expr, \
    662 SCIP_INTERVAL bounds, \
    663 SCIP_INTERVAL* childrenbounds, \
    664 SCIP_Bool* infeasible)
    665
    666/** expression callback to get information for symmetry detection
    667 *
    668 * The method returns information regarding constants and coefficients used in an expression.
    669 *
    670 * \param[in] scip SCIP main data structure
    671 * \param[in] expr expression to retrieve information from
    672 * \param[out] exprdata buffer to store retrieved data
    673 */
    674#define SCIP_DECL_EXPRGETSYMDATA(x) SCIP_RETCODE x (\
    675 SCIP* scip, \
    676 SCIP_EXPR* expr, \
    677 SYM_EXPRDATA** symdata)
    678
    679/** @} */ /* expression handler */
    680
    681
    682
    683/** @name Expression iterator
    684 * @{
    685 */
    686
    687/** maximal number of iterators that can be active on an expression graph concurrently
    688 *
    689 * How often an expression graph iteration can be started within an active iteration, plus one.
    690 */
    691#define SCIP_EXPRITER_MAXNACTIVE 5
    692
    693/* stages of expression DFS iteration */
    694#define SCIP_EXPRITER_ENTEREXPR 1u /**< an expression is visited the first time (before any of its children are visited) */
    695#define SCIP_EXPRITER_VISITINGCHILD 2u /**< a child of an expression is to be visited */
    696#define SCIP_EXPRITER_VISITEDCHILD 4u /**< a child of an expression has been visited */
    697#define SCIP_EXPRITER_LEAVEEXPR 8u /**< an expression is to be left (all of its children have been processed) */
    698#define SCIP_EXPRITER_ALLSTAGES (SCIP_EXPRITER_ENTEREXPR | SCIP_EXPRITER_VISITINGCHILD | SCIP_EXPRITER_VISITEDCHILD | SCIP_EXPRITER_LEAVEEXPR)
    699
    700/** stage of DFS iterator */
    701typedef unsigned int SCIP_EXPRITER_STAGE;
    702
    703/** user data storage type for expression iteration */
    704typedef union
    705{
    706 SCIP_Real realval; /**< a floating-point value */
    707 int intval; /**< an integer value */
    708 int intvals[2]; /**< two integer values */
    709 unsigned int uintval; /**< an unsigned integer value */
    710 void* ptrval; /**< a pointer */
    712
    713/** mode for expression iterator */
    714typedef enum
    715{
    716 SCIP_EXPRITER_RTOPOLOGIC, /**< reverse topological order */
    717 SCIP_EXPRITER_BFS, /**< breadth-first search */
    718 SCIP_EXPRITER_DFS /**< depth-first search */
    720
    721typedef struct SCIP_ExprIterData SCIP_EXPRITERDATA; /**< expression iterator data of a specific expression */
    722typedef struct SCIP_ExprIter SCIP_EXPRITER; /**< expression iterator */
    723
    724/** @} */ /* expression iterator */
    725
    726/** @name Expression printing
    727 * @{
    728 */
    729
    730#define SCIP_EXPRPRINT_EXPRSTRING 0x1u /**< print the math. function that the expression represents (e.g., "c0+c1") */
    731#define SCIP_EXPRPRINT_EXPRHDLR 0x2u /**< print expression handler name */
    732#define SCIP_EXPRPRINT_NUSES 0x4u /**< print number of uses (reference counting) */
    733#define SCIP_EXPRPRINT_EVALVALUE 0x8u /**< print evaluation value */
    734#define SCIP_EXPRPRINT_EVALTAG 0x18u /**< print evaluation value and tag */
    735#define SCIP_EXPRPRINT_ACTIVITY 0x20u /**< print activity value */
    736#define SCIP_EXPRPRINT_ACTIVITYTAG 0x60u /**< print activity value and corresponding tag */
    737#define SCIP_EXPRPRINT_OWNER 0x80u /**< print ownerdata */
    738
    739/** print everything */
    740#define SCIP_EXPRPRINT_ALL SCIP_EXPRPRINT_EXPRSTRING | SCIP_EXPRPRINT_EXPRHDLR | SCIP_EXPRPRINT_NUSES | SCIP_EXPRPRINT_EVALTAG | SCIP_EXPRPRINT_ACTIVITYTAG | SCIP_EXPRPRINT_OWNER
    741
    742typedef unsigned int SCIP_EXPRPRINT_WHAT; /**< exprprint bitflags */
    743typedef struct SCIP_ExprPrintData SCIP_EXPRPRINTDATA; /**< data when printing an expression */
    744
    745/** @} */
    746
    747
    748#endif /* SCIP_TYPE_EXPR_H_ */
    common defines and data types used in all packages of SCIP
    #define SCIP_Real
    Definition: def.h:156
    interval arithmetics for provable bounds
    struct SCIP_ExprhdlrData SCIP_EXPRHDLRDATA
    Definition: type_expr.h:195
    struct SCIP_ExprData SCIP_EXPRDATA
    Definition: type_expr.h:54
    struct SCIP_ExprIterData SCIP_EXPRITERDATA
    Definition: type_expr.h:721
    SCIP_EXPRCURV
    Definition: type_expr.h:61
    @ SCIP_EXPRCURV_CONVEX
    Definition: type_expr.h:63
    @ SCIP_EXPRCURV_LINEAR
    Definition: type_expr.h:65
    @ SCIP_EXPRCURV_UNKNOWN
    Definition: type_expr.h:62
    @ SCIP_EXPRCURV_CONCAVE
    Definition: type_expr.h:64
    struct SCIP_Expr_OwnerData SCIP_EXPR_OWNERDATA
    Definition: type_expr.h:80
    SCIP_MONOTONE
    Definition: type_expr.h:70
    @ SCIP_MONOTONE_CONST
    Definition: type_expr.h:74
    @ SCIP_MONOTONE_UNKNOWN
    Definition: type_expr.h:71
    @ SCIP_MONOTONE_INC
    Definition: type_expr.h:72
    @ SCIP_MONOTONE_DEC
    Definition: type_expr.h:73
    unsigned int SCIP_EXPRPRINT_WHAT
    Definition: type_expr.h:742
    SCIP_EXPRITER_TYPE
    Definition: type_expr.h:715
    @ SCIP_EXPRITER_BFS
    Definition: type_expr.h:717
    @ SCIP_EXPRITER_DFS
    Definition: type_expr.h:718
    @ SCIP_EXPRITER_RTOPOLOGIC
    Definition: type_expr.h:716
    struct SCIP_ExprPrintData SCIP_EXPRPRINTDATA
    Definition: type_expr.h:743
    unsigned int SCIP_EXPRITER_STAGE
    Definition: type_expr.h:701
    type definitions for return codes for SCIP methods
    type definitions for SCIP's main datastructure
    type definitions for storing primal CIP solutions
    type definitions for branch and bound tree
    type definitions for problem variables
    unsigned int uintval
    Definition: type_expr.h:709