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