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 pub_expr.h 26 * @ingroup PUBLICCOREAPI 27 * @brief public functions to work with algebraic expressions 28 * @author Ksenia Bestuzheva 29 * @author Benjamin Mueller 30 * @author Felipe Serrano 31 * @author Stefan Vigerske 32 */ 33 34 #ifndef SCIP_PUB_EXPR_H_ 35 #define SCIP_PUB_EXPR_H_ 36 37 #include "scip/def.h" 38 #include "scip/type_expr.h" 39 #include "scip/type_misc.h" 40 41 #ifdef NDEBUG 42 #include "scip/struct_expr.h" 43 #endif 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /**@addtogroup PublicExprHandlerMethods 50 * @{ 51 */ 52 53 /** set the expression handler callbacks to copy and free an expression handler */ 54 SCIP_EXPORT 55 void SCIPexprhdlrSetCopyFreeHdlr( 56 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 57 SCIP_DECL_EXPRCOPYHDLR((*copyhdlr)), /**< handler copy callback (can be NULL) */ 58 SCIP_DECL_EXPRFREEHDLR((*freehdlr)) /**< handler free callback (can be NULL) */ 59 ); 60 61 /** set the expression handler callbacks to copy and free expression data */ 62 SCIP_EXPORT 63 void SCIPexprhdlrSetCopyFreeData( 64 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 65 SCIP_DECL_EXPRCOPYDATA((*copydata)), /**< expression data copy callback (can be NULL for expressions without data) */ 66 SCIP_DECL_EXPRFREEDATA((*freedata)) /**< expression data free callback (can be NULL if data does not need to be freed) */ 67 ); 68 69 /** set the print callback of an expression handler */ 70 SCIP_EXPORT 71 void SCIPexprhdlrSetPrint( 72 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 73 SCIP_DECL_EXPRPRINT((*print)) /**< print callback (can be NULL) */ 74 ); 75 76 /** set the parse callback of an expression handler */ 77 SCIP_EXPORT 78 void SCIPexprhdlrSetParse( 79 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 80 SCIP_DECL_EXPRPARSE((*parse)) /**< parse callback (can be NULL) */ 81 ); 82 83 /** set the curvature detection callback of an expression handler */ 84 SCIP_EXPORT 85 void SCIPexprhdlrSetCurvature( 86 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 87 SCIP_DECL_EXPRCURVATURE((*curvature)) /**< curvature detection callback (can be NULL) */ 88 ); 89 90 /** set the monotonicity detection callback of an expression handler */ 91 SCIP_EXPORT 92 void SCIPexprhdlrSetMonotonicity( 93 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 94 SCIP_DECL_EXPRMONOTONICITY((*monotonicity)) /**< monotonicity detection callback (can be NULL) */ 95 ); 96 97 /** set the integrality detection callback of an expression handler */ 98 SCIP_EXPORT 99 void SCIPexprhdlrSetIntegrality( 100 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 101 SCIP_DECL_EXPRINTEGRALITY((*integrality)) /**< integrality detection callback (can be NULL) */ 102 ); 103 104 /** set the hash callback of an expression handler */ 105 SCIP_EXPORT 106 void SCIPexprhdlrSetHash( 107 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 108 SCIP_DECL_EXPRHASH((*hash)) /**< hash callback (can be NULL) */ 109 ); 110 111 /** set the compare callback of an expression handler */ 112 SCIP_EXPORT 113 void SCIPexprhdlrSetCompare( 114 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 115 SCIP_DECL_EXPRCOMPARE((*compare)) /**< compare callback (can be NULL) */ 116 ); 117 118 /** set differentiation callbacks of an expression handler */ 119 SCIP_EXPORT 120 void SCIPexprhdlrSetDiff( 121 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 122 SCIP_DECL_EXPRBWDIFF((*bwdiff)), /**< backward derivative evaluation callback (can be NULL) */ 123 SCIP_DECL_EXPRFWDIFF((*fwdiff)), /**< forward derivative evaluation callback (can be NULL) */ 124 SCIP_DECL_EXPRBWFWDIFF((*bwfwdiff)) /**< backward-forward derivative evaluation callback (can be NULL) */ 125 ); 126 127 /** set the interval evaluation callback of an expression handler */ 128 SCIP_EXPORT 129 void SCIPexprhdlrSetIntEval( 130 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 131 SCIP_DECL_EXPRINTEVAL((*inteval)) /**< interval evaluation callback (can be NULL) */ 132 ); 133 134 /** set the simplify callback of an expression handler */ 135 SCIP_EXPORT 136 void SCIPexprhdlrSetSimplify( 137 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 138 SCIP_DECL_EXPRSIMPLIFY((*simplify)) /**< simplify callback (can be NULL) */ 139 ); 140 141 /** set the reverse propagation callback of an expression handler */ 142 SCIP_EXPORT 143 void SCIPexprhdlrSetReverseProp( 144 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 145 SCIP_DECL_EXPRREVERSEPROP((*reverseprop)) /**< reverse propagation callback (can be NULL) */ 146 ); 147 148 /** set the estimation callbacks of an expression handler */ 149 SCIP_EXPORT 150 void SCIPexprhdlrSetEstimate( 151 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 152 SCIP_DECL_EXPRINITESTIMATES((*initestimates)), /**< initial estimators callback (can be NULL) */ 153 SCIP_DECL_EXPRESTIMATE((*estimate)) /**< estimator callback (can be NULL) */ 154 ); 155 156 /** set the symmetry information callback of an expression handler */ 157 SCIP_EXPORT 158 void SCIPexprhdlrSetGetSymdata( 159 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 160 SCIP_DECL_EXPRGETSYMDATA((*getsymdata)) /**< get symmetry data callback (can be NULL) */ 161 ); 162 163 /** gives the name of an expression handler */ 164 SCIP_EXPORT 165 const char* SCIPexprhdlrGetName( 166 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 167 ); 168 169 /** gives the description of an expression handler (can be NULL) */ 170 SCIP_EXPORT 171 const char* SCIPexprhdlrGetDescription( 172 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 173 ); 174 175 /** gives the precedence of an expression handler */ 176 SCIP_EXPORT 177 unsigned int SCIPexprhdlrGetPrecedence( 178 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 179 ); 180 181 /** gives the data of an expression handler */ 182 SCIP_EXPORT 183 SCIP_EXPRHDLRDATA* SCIPexprhdlrGetData( 184 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 185 ); 186 187 /** returns whether expression handler implements the print callback */ 188 SCIP_EXPORT 189 SCIP_Bool SCIPexprhdlrHasPrint( 190 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 191 ); 192 193 /** returns whether expression handler implements the backward differentiation callback */ 194 SCIP_EXPORT 195 SCIP_Bool SCIPexprhdlrHasBwdiff( 196 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 197 ); 198 199 /** returns whether expression handler implements the forward differentiation callback */ 200 SCIP_EXPORT 201 SCIP_Bool SCIPexprhdlrHasFwdiff( 202 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 203 ); 204 205 /** returns whether expression handler implements the interval evaluation callback */ 206 SCIP_EXPORT 207 SCIP_Bool SCIPexprhdlrHasIntEval( 208 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 209 ); 210 211 /** returns whether expression handler implements the estimator callback */ 212 SCIP_EXPORT 213 SCIP_Bool SCIPexprhdlrHasEstimate( 214 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 215 ); 216 217 /** returns whether expression handler implements the initial estimators callback */ 218 SCIP_EXPORT 219 SCIP_Bool SCIPexprhdlrHasInitEstimates( 220 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 221 ); 222 223 /** returns whether expression handler implements the simplification callback */ 224 SCIP_EXPORT 225 SCIP_Bool SCIPexprhdlrHasSimplify( 226 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 227 ); 228 229 /** returns whether expression handler implements the curvature callback */ 230 SCIP_EXPORT 231 SCIP_Bool SCIPexprhdlrHasCurvature( 232 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 233 ); 234 235 /** returns whether expression handler implements the monotonicity callback */ 236 SCIP_EXPORT 237 SCIP_Bool SCIPexprhdlrHasMonotonicity( 238 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 239 ); 240 241 /** returns whether expression handler implements the reverse propagation callback */ 242 SCIP_EXPORT 243 SCIP_Bool SCIPexprhdlrHasReverseProp( 244 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 245 ); 246 247 /** return whether expression handler implements the symmetry data callback */ 248 SCIP_EXPORT 249 SCIP_Bool SCIPexprhdlrHasGetSymData( 250 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 251 ); 252 253 /** compares two expression handler w.r.t. their name */ 254 SCIP_EXPORT 255 SCIP_DECL_SORTPTRCOMP(SCIPexprhdlrComp); 256 257 /**@name Expression Handler Statistics */ 258 /**@{ */ 259 260 /** gets number of times an expression has been created with given expression handler */ 261 SCIP_EXPORT 262 unsigned int SCIPexprhdlrGetNCreated( 263 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 264 ); 265 266 /** gets number of times the interval evaluation callback was called */ 267 SCIP_EXPORT 268 SCIP_Longint SCIPexprhdlrGetNIntevalCalls( 269 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 270 ); 271 272 /** gets time spend in interval evaluation callback */ 273 SCIP_EXPORT 274 SCIP_Real SCIPexprhdlrGetIntevalTime( 275 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 276 ); 277 278 /** gets number of times the reverse propagation callback was called */ 279 SCIP_EXPORT 280 SCIP_Longint SCIPexprhdlrGetNReversepropCalls( 281 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 282 ); 283 284 /** gets time spend in reverse propagation callback */ 285 SCIP_EXPORT 286 SCIP_Real SCIPexprhdlrGetReversepropTime( 287 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 288 ); 289 290 /** gets number of times an empty interval was found in reverse propagation */ 291 SCIP_EXPORT 292 SCIP_Longint SCIPexprhdlrGetNCutoffs( 293 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 294 ); 295 296 /** gets number of times a bound reduction was found in reverse propagation (and accepted by caller) */ 297 SCIP_EXPORT 298 SCIP_Longint SCIPexprhdlrGetNDomainReductions( 299 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 300 ); 301 302 /** increments the domain reductions count of an expression handler */ 303 SCIP_EXPORT 304 void SCIPexprhdlrIncrementNDomainReductions( 305 SCIP_EXPRHDLR* exprhdlr, /**< expression handler */ 306 int nreductions /**< number of reductions to add to counter */ 307 ); 308 309 /** gets number of times the estimation callback was called */ 310 SCIP_EXPORT 311 SCIP_Longint SCIPexprhdlrGetNEstimateCalls( 312 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 313 ); 314 315 /** gets time spend in estimation callback */ 316 SCIP_EXPORT 317 SCIP_Real SCIPexprhdlrGetEstimateTime( 318 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 319 ); 320 321 /** gets number of times branching candidates reported by of this expression handler were used to assemble branching candidates 322 * 323 * that is, how often did we consider branching on a child of this expression 324 */ 325 SCIP_EXPORT 326 SCIP_Longint SCIPexprhdlrGetNBranchings( 327 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 328 ); 329 330 /** increments the branching candidates count of an expression handler */ 331 SCIP_EXPORT 332 void SCIPexprhdlrIncrementNBranchings( 333 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 334 ); 335 336 /** gets number of times the simplify callback was called */ 337 SCIP_EXPORT 338 SCIP_Longint SCIPexprhdlrGetNSimplifyCalls( 339 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 340 ); 341 342 /** gets time spend in simplify callback */ 343 SCIP_EXPORT 344 SCIP_Real SCIPexprhdlrGetSimplifyTime( 345 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 346 ); 347 348 /** gets number of times the simplify callback found a simplification */ 349 SCIP_EXPORT 350 SCIP_Longint SCIPexprhdlrGetNSimplifications( 351 SCIP_EXPRHDLR* exprhdlr /**< expression handler */ 352 ); 353 354 /** @} */ /* expression handler statistics */ 355 356 #ifdef NDEBUG 357 358 /* If NDEBUG is defined, the function calls are overwritten by defines to reduce the number of function calls and 359 * speed up the algorithms. 360 */ 361 362 #define SCIPexprhdlrSetCopyFreeHdlr(exprhdlr, copyhdlr_, freehdlr_) do { (exprhdlr)->copyhdlr = copyhdlr_; (exprhdlr)->freehdlr = freehdlr_; } while (FALSE) 363 #define SCIPexprhdlrSetCopyFreeData(exprhdlr, copydata_, freedata_) do { (exprhdlr)->copydata = copydata_; (exprhdlr)->freedata = freedata_; } while (FALSE) 364 #define SCIPexprhdlrSetPrint(exprhdlr, print_) (exprhdlr)->print = print_ 365 #define SCIPexprhdlrSetParse(exprhdlr, parse_) (exprhdlr)->parse = parse_ 366 #define SCIPexprhdlrSetCurvature(exprhdlr, curvature_) (exprhdlr)->curvature = curvature_ 367 #define SCIPexprhdlrSetMonotonicity(exprhdlr, monotonicity_) (exprhdlr)->monotonicity = monotonicity_ 368 #define SCIPexprhdlrSetIntegrality(exprhdlr, integrality_) (exprhdlr)->integrality = integrality_ 369 #define SCIPexprhdlrSetHash(exprhdlr, hash_) (exprhdlr)->hash = hash_ 370 #define SCIPexprhdlrSetCompare(exprhdlr, compare_) (exprhdlr)->compare = compare_ 371 #define SCIPexprhdlrSetDiff(exprhdlr, bwdiff_, fwdiff_, bwfwdiff_) do { (exprhdlr)->bwdiff = bwdiff_; (exprhdlr)->fwdiff = fwdiff_; (exprhdlr)->bwfwdiff = bwfwdiff_; } while (FALSE) 372 #define SCIPexprhdlrSetIntEval(exprhdlr, inteval_) (exprhdlr)->inteval = inteval_ 373 #define SCIPexprhdlrSetSimplify(exprhdlr, simplify_) (exprhdlr)->simplify = simplify_ 374 #define SCIPexprhdlrSetReverseProp(exprhdlr, reverseprop_) (exprhdlr)->reverseprop = reverseprop_ 375 #define SCIPexprhdlrSetEstimate(exprhdlr, initestimates_, estimate_) do { (exprhdlr)->initestimates = initestimates_; (exprhdlr)->estimate = estimate_; } while (FALSE) 376 #define SCIPexprhdlrSetGetSymdata(exprhdlr, getsymdata_) (exprhdlr)->getsymdata = getsymdata_ 377 #define SCIPexprhdlrGetName(exprhdlr) (exprhdlr)->name 378 #define SCIPexprhdlrGetDescription(exprhdlr) (exprhdlr)->desc 379 #define SCIPexprhdlrGetPrecedence(exprhdlr) (exprhdlr)->precedence 380 #define SCIPexprhdlrGetData(exprhdlr) (exprhdlr)->data 381 #define SCIPexprhdlrHasPrint(exprhdlr) ((exprhdlr)->print != NULL) 382 #define SCIPexprhdlrHasBwdiff(exprhdlr) ((exprhdlr)->bwdiff != NULL) 383 #define SCIPexprhdlrHasFwdiff(exprhdlr) ((exprhdlr)->fwdiff != NULL) 384 #define SCIPexprhdlrHasIntEval(exprhdlr) ((exprhdlr)->inteval != NULL) 385 #define SCIPexprhdlrHasEstimate(exprhdlr) ((exprhdlr)->estimate != NULL) 386 #define SCIPexprhdlrHasInitEstimates(exprhdlr) ((exprhdlr)->initestimates != NULL) 387 #define SCIPexprhdlrHasSimplify(exprhdlr) ((exprhdlr)->simplify != NULL) 388 #define SCIPexprhdlrHasCurvature(exprhdlr) ((exprhdlr)->curvature != NULL) 389 #define SCIPexprhdlrHasMonotonicity(exprhdlr) ((exprhdlr)->monotonicity != NULL) 390 #define SCIPexprhdlrHasReverseProp(exprhdlr) ((exprhdlr)->reverseprop != NULL) 391 #define SCIPexprhdlrGetNCreated(exprhdlr) (exprhdlr)->ncreated 392 #define SCIPexprhdlrGetNIntevalCalls(exprhdlr) (exprhdlr)->nintevalcalls 393 #define SCIPexprhdlrGetIntevalTime(exprhdlr) SCIPclockGetTime((exprhdlr)->intevaltime) 394 #define SCIPexprhdlrGetNReversepropCalls(exprhdlr) (exprhdlr)->npropcalls 395 #define SCIPexprhdlrGetReversepropTime(exprhdlr) SCIPclockGetTime((exprhdlr)->proptime) 396 #define SCIPexprhdlrGetNCutoffs(exprhdlr) (exprhdlr)->ncutoffs 397 #define SCIPexprhdlrGetNDomainReductions(exprhdlr) (exprhdlr)->ndomreds 398 #define SCIPexprhdlrIncrementNDomainReductions(exprhdlr, nreductions) (exprhdlr)->ndomreds += nreductions 399 #define SCIPexprhdlrGetNEstimateCalls(exprhdlr) (exprhdlr)->nestimatecalls 400 #define SCIPexprhdlrGetEstimateTime(exprhdlr) SCIPclockGetTime((exprhdlr)->estimatetime) 401 #define SCIPexprhdlrGetNBranchings(exprhdlr) (exprhdlr)->nbranchscores 402 #define SCIPexprhdlrIncrementNBranchings(exprhdlr) ++(exprhdlr)->nbranchscores 403 #define SCIPexprhdlrGetNSimplifyCalls(exprhdlr) (exprhdlr)->nsimplifycalls 404 #define SCIPexprhdlrGetSimplifyTime(exprhdlr) SCIPclockGetTime((exprhdlr)->simplifytime) 405 #define SCIPexprhdlrGetNSimplifications(exprhdlr) (exprhdlr)->nsimplified 406 #endif 407 408 409 /** @} */ /* expression handler methods */ 410 411 /**@defgroup PublicExprMethods Expressions 412 * @ingroup DataStructures 413 * @brief an algebraic expression used for nonlinear constraints and NLPs 414 * 415 *@{ 416 */ 417 418 /**@name Expressions */ 419 /**@{ */ 420 421 /** gets the number of times the expression is currently captured */ 422 SCIP_EXPORT 423 int SCIPexprGetNUses( 424 SCIP_EXPR* expr /**< expression */ 425 ); 426 427 /** gives the number of children of an expression */ 428 SCIP_EXPORT 429 int SCIPexprGetNChildren( 430 SCIP_EXPR* expr /**< expression */ 431 ); 432 433 /** gives the children of an expression (can be NULL if no children) */ 434 SCIP_EXPORT 435 SCIP_EXPR** SCIPexprGetChildren( 436 SCIP_EXPR* expr /**< expression */ 437 ); 438 439 /** gets the expression handler of an expression 440 * 441 * This identifies the type of the expression (sum, variable, ...). 442 */ 443 SCIP_EXPORT 444 SCIP_EXPRHDLR* SCIPexprGetHdlr( 445 SCIP_EXPR* expr /**< expression */ 446 ); 447 448 /** gets the expression data of an expression */ 449 SCIP_EXPORT 450 SCIP_EXPRDATA* SCIPexprGetData( 451 SCIP_EXPR* expr /**< expression */ 452 ); 453 454 /** sets the expression data of an expression 455 * 456 * The pointer to possible old data is overwritten and the 457 * freedata-callback is not called before. 458 * This function is intended to be used by expression handler only. 459 */ 460 SCIP_EXPORT 461 void SCIPexprSetData( 462 SCIP_EXPR* expr, /**< expression */ 463 SCIP_EXPRDATA* exprdata /**< expression data to be set (can be NULL) */ 464 ); 465 466 /** gets the data that the owner of an expression has stored in an expression */ 467 SCIP_EXPORT 468 SCIP_EXPR_OWNERDATA* SCIPexprGetOwnerData( 469 SCIP_EXPR* expr /**< expression */ 470 ); 471 472 /** gives the value from the last evaluation of an expression (or SCIP_INVALID if there was an eval error) 473 * 474 * @see SCIPevalExpr to evaluate the expression at a given solution. 475 */ 476 SCIP_EXPORT 477 SCIP_Real SCIPexprGetEvalValue( 478 SCIP_EXPR* expr /**< expression */ 479 ); 480 481 /** gives the evaluation tag from the last evaluation, or 0 482 * 483 * @see SCIPevalExpr 484 */ 485 SCIP_EXPORT 486 SCIP_Longint SCIPexprGetEvalTag( 487 SCIP_EXPR* expr /**< expression */ 488 ); 489 490 /** returns the derivative stored in an expression (or SCIP_INVALID if there was an evaluation error) 491 * 492 * @see SCIPevalExprGradient 493 */ 494 SCIP_EXPORT 495 SCIP_Real SCIPexprGetDerivative( 496 SCIP_EXPR* expr /**< expression */ 497 ); 498 499 /** gives the value of directional derivative from the last evaluation of a directional derivative of expression 500 * (or SCIP_INVALID if there was an error) 501 * 502 * @see SCIPevalExprHessianDir 503 */ 504 SCIP_EXPORT 505 SCIP_Real SCIPexprGetDot( 506 SCIP_EXPR* expr /**< expression */ 507 ); 508 509 /** gives the value of directional derivative from the last evaluation of a directional derivative of derivative 510 * of root (or SCIP_INVALID if there was an error) 511 * 512 * @see SCIPevalExprHessianDir 513 */ 514 SCIP_EXPORT 515 SCIP_Real SCIPexprGetBardot( 516 SCIP_EXPR* expr /**< expression */ 517 ); 518 519 /** returns the difftag stored in an expression 520 * 521 * can be used to check whether partial derivative value is valid 522 * 523 * @see SCIPevalExprGradient 524 */ 525 SCIP_EXPORT 526 SCIP_Longint SCIPexprGetDiffTag( 527 SCIP_EXPR* expr /**< expression */ 528 ); 529 530 /** returns the activity that is currently stored for an expression 531 * 532 * @see SCIPevalExprActivity 533 */ 534 SCIP_EXPORT 535 SCIP_INTERVAL SCIPexprGetActivity( 536 SCIP_EXPR* expr /**< expression */ 537 ); 538 539 /** returns the tag associated with the activity of the expression 540 * 541 * It can depend on the owner of the expression how to interpret this tag. 542 * SCIPevalExprActivity() compares with `stat->domchgcount`. 543 * 544 * @see SCIPevalExprActivity 545 */ 546 SCIP_EXPORT 547 SCIP_Longint SCIPexprGetActivityTag( 548 SCIP_EXPR* expr /**< expression */ 549 ); 550 551 /** set the activity with tag for an expression */ 552 SCIP_EXPORT 553 void SCIPexprSetActivity( 554 SCIP_EXPR* expr, /**< expression */ 555 SCIP_INTERVAL activity, /**< new activity */ 556 SCIP_Longint activitytag /**< tag associated with activity */ 557 ); 558 559 /** returns the curvature of an expression 560 * 561 * @note Call SCIPcomputeExprCurvature() before calling this function. 562 */ 563 SCIP_EXPORT 564 SCIP_EXPRCURV SCIPexprGetCurvature( 565 SCIP_EXPR* expr /**< expression */ 566 ); 567 568 /** sets the curvature of an expression */ 569 SCIP_EXPORT 570 void SCIPexprSetCurvature( 571 SCIP_EXPR* expr, /**< expression */ 572 SCIP_EXPRCURV curvature /**< curvature of the expression */ 573 ); 574 575 /** returns whether an expression is integral */ 576 SCIP_EXPORT 577 SCIP_Bool SCIPexprIsIntegral( 578 SCIP_EXPR* expr /**< expression */ 579 ); 580 581 /** sets the integrality flag of an expression */ 582 SCIP_EXPORT 583 void SCIPexprSetIntegrality( 584 SCIP_EXPR* expr, /**< expression */ 585 SCIP_Bool isintegral /**< integrality of the expression */ 586 ); 587 588 /** @} */ 589 590 /**@name Quadratic Expressions */ 591 /**@{ */ 592 593 /** gives the coefficients and expressions that define a quadratic expression 594 * 595 * It can return the constant part, the number, arguments, and coefficients of the purely linear part 596 * and the number of quadratic terms and bilinear terms. 597 * Note that for arguments that appear in the quadratic part, a linear coefficient is 598 * stored with the quadratic term. 599 * Use SCIPexprGetQuadraticQuadTerm() and SCIPexprGetQuadraticBilinTerm() 600 * to access the data for a quadratic or bilinear term. 601 * 602 * It can also return the eigenvalues and the eigenvectors of the matrix \f$Q\f$ when the quadratic is written 603 * as \f$x^T Q x + b^T x + c^T y + d\f$, where \f$c^T y\f$ defines the purely linear part. 604 * Note, however, that to have access to them one needs to call SCIPcomputeExprQuadraticCurvature() 605 * with `storeeigeninfo=TRUE`. If the eigen information was not stored or it failed to be computed, 606 * `eigenvalues` and `eigenvectors` will be set to NULL. 607 * 608 * This function returns pointers to internal data in linexprs and lincoefs. 609 * The user must not change this data. 610 * 611 * @attention SCIPcheckExprQuadratic() needs to be called first to check whether expression is quadratic and initialize the data of the quadratic representation. 612 */ 613 SCIP_EXPORT 614 void SCIPexprGetQuadraticData( 615 SCIP_EXPR* expr, /**< quadratic expression */ 616 SCIP_Real* constant, /**< buffer to store constant term, or NULL */ 617 int* nlinexprs, /**< buffer to store number of expressions that appear linearly, or NULL */ 618 SCIP_EXPR*** linexprs, /**< buffer to store pointer to array of expressions that appear linearly, or NULL */ 619 SCIP_Real** lincoefs, /**< buffer to store pointer to array of coefficients of expressions that appear linearly, or NULL */ 620 int* nquadexprs, /**< buffer to store number of expressions in quadratic terms, or NULL */ 621 int* nbilinexprs, /**< buffer to store number of bilinear expressions terms, or NULL */ 622 SCIP_Real** eigenvalues, /**< buffer to store pointer to array of eigenvalues of Q, or NULL */ 623 SCIP_Real** eigenvectors /**< buffer to store pointer to array of eigenvectors of Q, or NULL */ 624 ); 625 626 /** gives the data of a quadratic expression term 627 * 628 * For a term \f$a \cdot \text{expr}^2 + b \cdot \text{expr} + \sum_i (c_i \cdot \text{expr} \cdot \text{otherexpr}_i)\f$, returns 629 * `expr`, \f$a\f$, \f$b\f$, the number of summands, and indices of bilinear terms in the quadratic expressions `bilinexprterms`. 630 * 631 * This function returns pointers to internal data in adjbilin. 632 * The user must not change this data. 633 */ 634 SCIP_EXPORT 635 void SCIPexprGetQuadraticQuadTerm( 636 SCIP_EXPR* quadexpr, /**< quadratic expression */ 637 int termidx, /**< index of quadratic term */ 638 SCIP_EXPR** expr, /**< buffer to store pointer to argument expression (the 'x') of this term, or NULL */ 639 SCIP_Real* lincoef, /**< buffer to store linear coefficient of variable, or NULL */ 640 SCIP_Real* sqrcoef, /**< buffer to store square coefficient of variable, or NULL */ 641 int* nadjbilin, /**< buffer to store number of bilinear terms this variable is involved in, or NULL */ 642 int** adjbilin, /**< buffer to store pointer to indices of associated bilinear terms, or NULL */ 643 SCIP_EXPR** sqrexpr /**< buffer to store pointer to square expression (the 'x^2') of this term or NULL if no square expression, or NULL */ 644 ); 645 646 /** gives the data of a bilinear expression term 647 * 648 * For a term a*expr1*expr2, returns expr1, expr2, a, and 649 * the position of the quadratic expression term that uses expr2 in the quadratic expressions `quadexprterms`. 650 */ 651 SCIP_EXPORT 652 void SCIPexprGetQuadraticBilinTerm( 653 SCIP_EXPR* expr, /**< quadratic expression */ 654 int termidx, /**< index of bilinear term */ 655 SCIP_EXPR** expr1, /**< buffer to store first factor, or NULL */ 656 SCIP_EXPR** expr2, /**< buffer to store second factor, or NULL */ 657 SCIP_Real* coef, /**< buffer to coefficient, or NULL */ 658 int* pos2, /**< buffer to position of expr2 in quadexprterms array of quadratic expression, or NULL */ 659 SCIP_EXPR** prodexpr /**< buffer to store pointer to expression that is product if first and second factor, or NULL */ 660 ); 661 662 /** returns whether all expressions that are used in a quadratic expression are variable expressions 663 * 664 * @return TRUE iff all `linexprs` and `quadexprterms[.].expr` are variable expressions 665 */ 666 SCIP_EXPORT 667 SCIP_Bool SCIPexprAreQuadraticExprsVariables( 668 SCIP_EXPR* expr /**< quadratic expression */ 669 ); 670 671 /** @} */ 672 673 #ifdef NDEBUG 674 #define SCIPexprGetNUses(expr) (expr)->nuses 675 #define SCIPexprGetNChildren(expr) (expr)->nchildren 676 #define SCIPexprGetChildren(expr) (expr)->children 677 #define SCIPexprGetHdlr(expr) (expr)->exprhdlr 678 #define SCIPexprGetData(expr) (expr)->exprdata 679 #define SCIPexprSetData(expr, exprdata_) (expr)->exprdata = exprdata_ 680 #define SCIPexprGetOwnerData(expr) (expr)->ownerdata 681 #define SCIPexprGetEvalValue(expr) (expr)->evalvalue 682 #define SCIPexprGetEvalTag(expr) (expr)->evaltag 683 #define SCIPexprGetDerivative(expr) (expr)->derivative 684 #define SCIPexprGetDot(expr) (expr)->dot 685 #define SCIPexprGetBardot(expr) (expr)->bardot 686 #define SCIPexprGetDiffTag(expr) (expr)->difftag 687 #define SCIPexprGetActivity(expr) (expr)->activity 688 #define SCIPexprGetActivityTag(expr) (expr)->activitytag 689 #define SCIPexprSetActivity(expr, activity_, activitytag_) do { (expr)->activity = activity_; (expr)->activitytag = activitytag_; } while (FALSE) 690 #define SCIPexprGetCurvature(expr) (expr)->curvature 691 #define SCIPexprSetCurvature(expr, curvature_) (expr)->curvature = curvature_ 692 #define SCIPexprIsIntegral(expr) (expr)->isintegral 693 #define SCIPexprSetIntegrality(expr, isintegral_) expr->isintegral = isintegral_ 694 #define SCIPexprAreQuadraticExprsVariables(expr) (expr)->quaddata->allexprsarevars 695 #endif 696 697 /**@name Core Expression Handlers */ 698 /**@{ */ 699 /* these are here to have them accessible also in the expr core 700 * so these cannot make use of SCIP pointer 701 */ 702 703 /** gets the variable of a variable expression */ 704 SCIP_EXPORT 705 SCIP_VAR* SCIPgetVarExprVar( 706 SCIP_EXPR* expr /**< var expression */ 707 ); 708 709 /** gets the value of a constant value expression */ 710 SCIP_EXPORT 711 SCIP_Real SCIPgetValueExprValue( 712 SCIP_EXPR* expr /**< value expression */ 713 ); 714 715 /** gets the coefficients of a summation expression */ 716 SCIP_EXPORT 717 SCIP_Real* SCIPgetCoefsExprSum( 718 SCIP_EXPR* expr /**< sum expression */ 719 ); 720 721 /** gets the constant of a summation expression */ 722 SCIP_EXPORT 723 SCIP_Real SCIPgetConstantExprSum( 724 SCIP_EXPR* expr /**< sum expression */ 725 ); 726 727 /** gets the constant coefficient of a product expression */ 728 SCIP_EXPORT 729 SCIP_Real SCIPgetCoefExprProduct( 730 SCIP_EXPR* expr /**< product expression */ 731 ); 732 733 /** gets the exponent of a power or signed power expression */ 734 SCIP_EXPORT 735 SCIP_Real SCIPgetExponentExprPow( 736 SCIP_EXPR* expr /**< (signed) power expression */ 737 ); 738 739 #ifdef NDEBUG 740 #define SCIPgetVarExprVar(expr) ((SCIP_VAR*)SCIPexprGetData(expr)) 741 #endif 742 743 /**@} */ 744 745 746 /**@name Expression Iterator 747 * 748 * @anchor SCIP_EXPRITER_DFS 749 * More details on the DFS mode: 750 * Many algorithms over expression trees need to traverse the tree in depth-first manner and a 751 * natural way of implementing these algorithms is by using recursion. 752 * In general, a function which traverses the tree in depth-first looks like 753 * <pre> 754 * fun( expr ) 755 * enterexpr() 756 * continue skip or abort 757 * for( child in expr->children ) 758 * visitingchild() 759 * continue skip or abort 760 * fun(child, data, proceed) 761 * visitedchild() 762 * continue skip or abort 763 * leaveexpr() 764 * </pre> 765 * Given that some expressions might be quite deep we provide this functionality in an iterative fashion. 766 * 767 * Consider an expression (x*y) + z + log(x-y). 768 * The corresponding expression graph is 769 * <pre> 770 * [+] 771 * / | \ 772 * [*] | [log] 773 * / \ | | 774 * / \ | [-] 775 * | | | / \ 776 * [x] [y] [z] [x] [y] 777 * </pre> 778 * (where [x] and [y] are actually the same expression). 779 * 780 * If a pointer to the [+] expression is given as root to this expression, it will iterate 781 * the graph in a depth-first manner and stop at various stages. 782 * - When entering an expression, it stops in the \ref SCIP_EXPRITER_ENTEREXPR stage. 783 * The SCIPexpriterGetParentDFS() function indicates from where the expression has been entered (NULL for the root expression). 784 * - Before visiting a child of an expression, it stops in the \ref SCIP_EXPRITER_VISITINGCHILD stage. 785 * The SCIPexpriterGetChildIdxDFS() function returns which child will be visited (as an index in the current expr's children array). 786 * Use SCIPexpriterGetChildExprDFS() to obtain the corresponding expression. 787 * - When returning from visiting a child of an expression, it stops in the \ref SCIP_EXPRITER_VISITEDCHILD stage. 788 * Again the SCIPexpriterGetChildExprDFS() function returns which child has been visited. 789 * - When leaving an expression, it stops in the \ref SCIP_EXPRITER_LEAVEEXPR stage. 790 * 791 * Thus, for the above expression, the expression are visited in the following order and stages: 792 * - `enterexpr([+])` 793 * - `visitingchild([+])`, currentchild = 0 794 * - `enterexpr([*])` 795 * - `visitingchild([*])`, currentchild = 0 796 * - `enterexpr([x])` 797 * - `leaveexpr([x])` 798 * - `visitedchild([*])`, currentchild = 0 799 * - `visitingchild([*])`, currentchild = 1 800 * - `enterexpr([y])` 801 * - `leaveexpr([y])` 802 * - `visitedchild([*])`, currentchild = 1 803 * - `leaveexpr([*])` 804 * - `visitedchild([+])`, currentchild = 0 805 * - `visitingchild([+])`, currentchild = 1 806 * - `enterexpr([z])` 807 * - `leaveexpr([z])` 808 * - `visitedchild([+])`, currentchild = 1 809 * - `visitingchild([+])`, currentchild = 2 810 * - `enterexpr([log])` 811 * - `visitingchild([log])`, currentchild = 0 812 * - `enterexpr([-])` 813 * - `visitingchild([-])`, currentchild = 0 814 * - `enterexpr([x])` 815 * - `leaveexpr([x])` 816 * - `visitedchild([-])`, currentchild = 0 817 * - `visitingchild([-])`, currentchild = 1 818 * - `enterexpr([y])` 819 * - `leaveexpr([y])` 820 * - `visitedchild([-])`, currentchild = 1 821 * - `leaveexpr([-])` 822 * - `visitedchild([log])`, currentchild = 0 823 * - `leaveexpr([log])` 824 * - `visitedchild([+])` currentchild = 2 825 * - `leaveexpr([+])` 826 * 827 * The caller can direct the iterator to skip parts of the tree: 828 * - If calling SCIPexpriterSkipDFS() in SCIP_EXPRITER_ENTEREXPR stage, all children of that expression will be skipped. The SCIP_EXPRITER_LEAVEEXPR stage will still be next. 829 * - If calling SCIPexpriterSkipDFS() in SCIP_EXPRITER_VISITINGCHILD stage, visiting the current child will be skipped. 830 * - If calling SCIPexpriterSkipDFS() in SCIP_EXPRITER_VISITEDCHILD child, visiting the remaining children will be skipped. 831 * 832 * @{ 833 */ 834 835 /** returns whether expression iterator is currently initialized */ 836 SCIP_EXPORT 837 SCIP_Bool SCIPexpriterIsInit( 838 SCIP_EXPRITER* iterator /**< expression iterator */ 839 ); 840 841 /** initializes an expression iterator 842 * 843 * @note If `expr` is NULL, then iterator will be set into ended-state (SCIPexpriterIsEnd() is TRUE). Useful if following with SCIPexpriterRestartDFS(). 844 * 845 * If type is DFS, then `stopstages` will be set to \ref SCIP_EXPRITER_ENTEREXPR. 846 * Use `SCIPexpriterSetStagesDFS` to change this. 847 */ 848 SCIP_EXPORT 849 SCIP_RETCODE SCIPexpriterInit( 850 SCIP_EXPRITER* iterator, /**< expression iterator */ 851 SCIP_EXPR* expr, /**< expression of the iterator, can be NULL */ 852 SCIP_EXPRITER_TYPE type, /**< type of expression iterator */ 853 SCIP_Bool allowrevisit /**< whether expression are allowed to be visited more than once */ 854 ); 855 856 /** restarts an already initialized expression iterator in DFS mode 857 * 858 * The expression iterator will continue from the given expression, not revisiting expressions that 859 * this iterator has already been visited (if initialized with `allowrevisit=FALSE`) and giving access 860 * to the same iterator specified expression data that may have been set already. 861 * Also the stop-stages are not reset. 862 * 863 * If revisiting is forbidden and given expr has already been visited, then the iterator will behave 864 * as on the end of iteration (SCIPexpriterIsEnd() is TRUE). 865 * If the enterexpr stage is not one of the stop stages, then the iterator will be moved forward 866 * (SCIPexpriterGetNext() is called). 867 * 868 * @return The current expression. 869 */ 870 SCIP_EXPORT 871 SCIP_EXPR* SCIPexpriterRestartDFS( 872 SCIP_EXPRITER* iterator, /**< expression iterator */ 873 SCIP_EXPR* expr /**< expression of the iterator */ 874 ); 875 876 /** specifies in which stages to stop a DFS iterator 877 * 878 * Parameter `stopstages` should be a bitwise OR of different \ref SCIP_EXPRITER_STAGE values 879 * 880 * If the current stage is not one of the `stopstages`, then the iterator will be moved on. 881 */ 882 SCIP_EXPORT 883 void SCIPexpriterSetStagesDFS( 884 SCIP_EXPRITER* iterator, /**< expression iterator */ 885 SCIP_EXPRITER_STAGE stopstages /**< the stages in which to stop when iterating via DFS */ 886 ); 887 888 /** gets the current expression that the expression iterator points to */ 889 SCIP_EXPORT 890 SCIP_EXPR* SCIPexpriterGetCurrent( 891 SCIP_EXPRITER* iterator /**< expression iterator */ 892 ); 893 894 /** gets the current stage that the expression iterator is in when using DFS 895 * 896 * If the iterator has finished (SCIPexpriterIsEnd() is TRUE), then the stage is undefined. 897 */ 898 SCIP_EXPORT 899 SCIP_EXPRITER_STAGE SCIPexpriterGetStageDFS( 900 SCIP_EXPRITER* iterator /**< expression iterator */ 901 ); 902 903 /** gets the index of the child that the expression iterator considers when in DFS mode and stage \ref SCIP_EXPRITER_VISITINGCHILD or \ref SCIP_EXPRITER_VISITEDCHILD */ 904 SCIP_EXPORT 905 int SCIPexpriterGetChildIdxDFS( 906 SCIP_EXPRITER* iterator /**< expression iterator */ 907 ); 908 909 /** gets the child expression that the expression iterator considers when in DFS mode and stage \ref SCIP_EXPRITER_VISITINGCHILD or \ref SCIP_EXPRITER_VISITEDCHILD */ 910 SCIP_EXPORT 911 SCIP_EXPR* SCIPexpriterGetChildExprDFS( 912 SCIP_EXPRITER* iterator /**< expression iterator */ 913 ); 914 915 /** gives the parent of the current expression of an expression iteration if in DFS mode 916 * 917 * @return the expression from which the current expression has been accessed 918 */ 919 SCIP_EXPORT 920 SCIP_EXPR* SCIPexpriterGetParentDFS( 921 SCIP_EXPRITER* iterator /**< expression iterator */ 922 ); 923 924 /** gives the iterator specific user data of the current expression 925 * 926 * @note The expression iterator mode must be DFS or another mode with allowrevisit=FALSE 927 */ 928 SCIP_EXPORT 929 SCIP_EXPRITER_USERDATA SCIPexpriterGetCurrentUserData( 930 SCIP_EXPRITER* iterator /**< expression iterator */ 931 ); 932 933 /** gives the iterator specific user data of the current expressions current child 934 * 935 * @note The expression iterator mode must be in DFS mode and stage \ref SCIP_EXPRITER_VISITINGCHILD or \ref SCIP_EXPRITER_VISITEDCHILD 936 */ 937 SCIP_EXPORT 938 SCIP_EXPRITER_USERDATA SCIPexpriterGetChildUserDataDFS( 939 SCIP_EXPRITER* iterator /**< expression iterator */ 940 ); 941 942 /** gives the iterator specific user data of a given expression 943 * 944 * @note The expression iterator mode must be DFS or another mode with allowrevisit=FALSE 945 */ 946 SCIP_EXPORT 947 SCIP_EXPRITER_USERDATA SCIPexpriterGetExprUserData( 948 SCIP_EXPRITER* iterator, /**< expression iterator */ 949 SCIP_EXPR* expr /**< expression for which to get the userdata of this iterator */ 950 ); 951 952 /** sets the iterator specific user data of the current expression for an expression iteration if in DFS mode 953 * 954 * @note The expression iterator mode must be DFS or another mode with allowrevisit=FALSE 955 */ 956 SCIP_EXPORT 957 void SCIPexpriterSetCurrentUserData( 958 SCIP_EXPRITER* iterator, /**< expression iterator */ 959 SCIP_EXPRITER_USERDATA userdata /**< data to be stored */ 960 ); 961 962 /** sets the iterator specific user data of a given expression 963 * 964 * @note The expression iterator mode must be DFS or another mode with allowrevisit=FALSE 965 */ 966 SCIP_EXPORT 967 void SCIPexpriterSetExprUserData( 968 SCIP_EXPRITER* iterator, /**< expression iterator */ 969 SCIP_EXPR* expr, /**< expression where to set iterator data */ 970 SCIP_EXPRITER_USERDATA userdata /**< data to be stored in current child */ 971 ); 972 973 /** sets the iterator specific user data of the current expressions current child 974 * 975 * @note The expression iterator mode must be in DFS mode and stage \ref SCIP_EXPRITER_VISITINGCHILD or \ref SCIP_EXPRITER_VISITEDCHILD 976 */ 977 SCIP_EXPORT 978 void SCIPexpriterSetChildUserData( 979 SCIP_EXPRITER* iterator, /**< expression iterator */ 980 SCIP_EXPRITER_USERDATA userdata /**< data to be stored in current child */ 981 ); 982 983 /** moves the iterator to the next expression according to the mode of the expression iterator 984 * 985 * @return the next expression, if any, and NULL otherwise 986 */ 987 SCIP_EXPORT 988 SCIP_EXPR* SCIPexpriterGetNext( 989 SCIP_EXPRITER* iterator /**< expression iterator */ 990 ); 991 992 /** moves a DFS iterator to one of the next expressions 993 * 994 * - If in \ref SCIP_EXPRITER_ENTEREXPR stage, then all children of that expression will be skipped. 995 * If \ref SCIP_EXPRITER_LEAVEEXPR is one of the `stopstages`, then it will be the next stage. Otherwise, the iterator will move further on (go to the parent, etc). 996 * - If in \ref SCIP_EXPRITER_VISITINGCHILD stage, then the child that was going to be visited next will be skipped and the iterator will be moved on to the next child (if any). 997 * - If in \ref SCIP_EXPRITER_VISITEDCHILD stage, then all remaining children will be skipped and we move on to the \ref SCIP_EXPRITER_LEAVEEXPR stage (if a stop stage, otherwise further on). 998 * - It is not allowed to call this function when in \ref SCIP_EXPRITER_LEAVEEXPR stage. 999 * 1000 * @return the next expression, if any, and NULL otherwise 1001 */ 1002 SCIP_EXPORT 1003 SCIP_EXPR* SCIPexpriterSkipDFS( 1004 SCIP_EXPRITER* iterator /**< expression iterator */ 1005 ); 1006 1007 /** returns whether the iterator visited all expressions already */ 1008 SCIP_EXPORT 1009 SCIP_Bool SCIPexpriterIsEnd( 1010 SCIP_EXPRITER* iterator /**< expression iterator */ 1011 ); 1012 1013 #ifdef NDEBUG 1014 #define SCIPexpriterIsInit(iterator) (iterator)->initialized 1015 #define SCIPexpriterGetCurrent(iterator) (iterator)->curr 1016 #define SCIPexpriterGetStageDFS(iterator) (iterator)->dfsstage 1017 #define SCIPexpriterGetChildIdxDFS(iterator) (iterator)->curr->iterdata[(iterator)->iterindex].currentchild 1018 #define SCIPexpriterGetChildExprDFS(iterator) (iterator)->curr->children[(iterator)->curr->iterdata[(iterator)->iterindex].currentchild] 1019 #define SCIPexpriterGetParentDFS(iterator) (iterator)->curr->iterdata[(iterator)->iterindex].parent 1020 #define SCIPexpriterGetCurrentUserData(iterator) (iterator)->curr->iterdata[(iterator)->iterindex].userdata 1021 #define SCIPexpriterGetChildUserDataDFS(iterator) (iterator)->curr->children[(iterator)->curr->iterdata[(iterator)->iterindex].currentchild]->iterdata[(iterator)->iterindex].userdata 1022 #define SCIPexpriterGetExprUserData(iterator, expr) (expr)->iterdata[(iterator)->iterindex].userdata 1023 #define SCIPexpriterSetCurrentUserData(iterator, userdata_) (iterator)->curr->iterdata[(iterator)->iterindex].userdata = userdata_ 1024 #define SCIPexpriterSetExprUserData(iterator, expr, userdata_) (expr)->iterdata[(iterator)->iterindex].userdata = userdata_ 1025 #define SCIPexpriterSetChildUserData(iterator, userdata_) (iterator)->curr->children[(iterator)->curr->iterdata[(iterator)->iterindex].currentchild]->iterdata[(iterator)->iterindex].userdata = userdata_ 1026 #define SCIPexpriterIsEnd(iterator) ((iterator)->curr == NULL) 1027 #endif 1028 1029 /** @} */ 1030 1031 /**@name Function Curvature */ 1032 /**@{ */ 1033 1034 /** gives curvature for a sum of two functions with given curvature */ 1035 SCIP_EXPORT 1036 SCIP_EXPRCURV SCIPexprcurvAdd( 1037 SCIP_EXPRCURV curv1, /**< curvature of first summand */ 1038 SCIP_EXPRCURV curv2 /**< curvature of second summand */ 1039 ); 1040 1041 /** gives the curvature for the negation of a function with given curvature */ 1042 SCIP_EXPORT 1043 SCIP_EXPRCURV SCIPexprcurvNegate( 1044 SCIP_EXPRCURV curvature /**< curvature of function */ 1045 ); 1046 1047 /** gives curvature for a functions with given curvature multiplied by a constant factor */ 1048 SCIP_EXPORT 1049 SCIP_EXPRCURV SCIPexprcurvMultiply( 1050 SCIP_Real factor, /**< constant factor */ 1051 SCIP_EXPRCURV curvature /**< curvature of other factor */ 1052 ); 1053 1054 /** gives curvature for base^exponent for given bounds and curvature of base-function and constant exponent */ 1055 SCIP_EXPORT 1056 SCIP_EXPRCURV SCIPexprcurvPower( 1057 SCIP_INTERVAL basebounds, /**< bounds on base function */ 1058 SCIP_EXPRCURV basecurv, /**< curvature of base function */ 1059 SCIP_Real exponent /**< exponent */ 1060 ); 1061 1062 /** gives required curvature for base so that base^exponent has given curvature under given bounds on base and constant exponent 1063 * 1064 * returns curvature unknown if expected curvature cannot be obtained 1065 */ 1066 SCIP_EXPORT 1067 SCIP_EXPRCURV SCIPexprcurvPowerInv( 1068 SCIP_INTERVAL basebounds, /**< bounds on base function */ 1069 SCIP_Real exponent, /**< exponent, must not be 0 */ 1070 SCIP_EXPRCURV powercurv /**< expected curvature for power */ 1071 ); 1072 1073 /** gives curvature for a monomial with given curvatures and bounds for each factor 1074 * 1075 * See Maranas and Floudas, Finding All Solutions of Nonlinearly Constrained Systems of Equations, JOGO 7, 1995 1076 * for the categorization in the case that all factors are linear. 1077 * 1078 * Exponents can also be negative or rational. 1079 */ 1080 SCIP_EXPORT 1081 SCIP_EXPRCURV SCIPexprcurvMonomial( 1082 int nfactors, /**< number of factors in monomial */ 1083 SCIP_Real* exponents, /**< exponents in monomial, or NULL if all 1.0 */ 1084 int* factoridxs, /**< indices of factors, or NULL if identity mapping */ 1085 SCIP_EXPRCURV* factorcurv, /**< curvature of each factor */ 1086 SCIP_INTERVAL* factorbounds /**< bounds of each factor */ 1087 ); 1088 1089 /** for a monomial with given bounds for each factor, gives condition on the curvature of each factor, so that monomial has a requested curvature, if possible 1090 * 1091 * @return whether `monomialcurv` can be achieved 1092 */ 1093 SCIP_EXPORT 1094 SCIP_Bool SCIPexprcurvMonomialInv( 1095 SCIP_EXPRCURV monomialcurv, /**< desired curvature */ 1096 int nfactors, /**< number of factors in monomial */ 1097 SCIP_Real* exponents, /**< exponents in monomial, or NULL if all 1.0 */ 1098 SCIP_INTERVAL* factorbounds, /**< bounds of each factor */ 1099 SCIP_EXPRCURV* factorcurv /**< buffer to store required curvature of each factor */ 1100 ); 1101 1102 /** gives name as string for a curvature */ 1103 SCIP_EXPORT 1104 const char* SCIPexprcurvGetName( 1105 SCIP_EXPRCURV curv /**< curvature */ 1106 ); 1107 1108 #ifdef NDEBUG 1109 #define SCIPexprcurvAdd(curv1, curv2) ((SCIP_EXPRCURV) ((curv1) & (curv2))) 1110 #define SCIPexprcurvNegate(curvature) (((curvature) == SCIP_EXPRCURV_CONCAVE) ? SCIP_EXPRCURV_CONVEX : ((curvature) == SCIP_EXPRCURV_CONVEX) ? SCIP_EXPRCURV_CONCAVE : (curvature)) 1111 #define SCIPexprcurvMultiply(factor, curvature) (((factor) == 0.0) ? SCIP_EXPRCURV_LINEAR : (factor) > 0.0 ? (curvature) : SCIPexprcurvNegate(curvature)) 1112 #endif 1113 1114 /**@} */ 1115 1116 /**@} */ 1117 1118 #ifdef __cplusplus 1119 } 1120 #endif 1121 1122 #endif /* SCIP_PUB_EXPR_H_ */ 1123