1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 2 /* */ 3 /* This file is part of the program and library */ 4 /* SCIP --- Solving Constraint Integer Programs */ 5 /* */ 6 /* Copyright (C) 2002-2021 Konrad-Zuse-Zentrum */ 7 /* fuer Informationstechnik Berlin */ 8 /* */ 9 /* SCIP is distributed under the terms of the ZIB Academic License. */ 10 /* */ 11 /* You should have received a copy of the ZIB Academic License */ 12 /* along with SCIP; see the file COPYING. If not visit scipopt.org. */ 13 /* */ 14 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 15 16 /**@file exprinterpret.h 17 * @brief methods to interpret (evaluate) an expression tree "fast" 18 * @author Stefan Vigerske 19 * @author Thorsten Gellermann 20 * Realized similar to LPI: one implementation of an interpreter is linked in. 21 */ 22 23 /* @todo product Gradient times vector 24 @todo product Hessian times vector 25 @todo product Hessian of Lagrangian times vector 26 @todo sparse Hessian of expression tree 27 @todo sparse Hessian of Lagrangian (sets of expression trees and quadratic parts)? 28 */ 29 30 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/ 31 32 #ifndef __SCIP_EXPRINTERPRET_H__ 33 #define __SCIP_EXPRINTERPRET_H__ 34 35 #include "scip/def.h" 36 #include "blockmemshell/memory.h" 37 #include "nlpi/type_expr.h" 38 #include "nlpi/type_exprinterpret.h" 39 #include "scip/intervalarith.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /**@addtogroup EXPRINTS 46 * @{ 47 */ 48 49 /** gets name and version of expression interpreter */ 50 SCIP_EXPORT 51 const char* SCIPexprintGetName(void); 52 53 /** gets descriptive text of expression interpreter */ 54 SCIP_EXPORT 55 const char* SCIPexprintGetDesc(void); 56 57 /** gets capabilities of expression interpreter (using bitflags) */ 58 SCIP_EXPORT 59 SCIP_EXPRINTCAPABILITY SCIPexprintGetCapability(void); 60 61 /** creates an expression interpreter object */ 62 SCIP_EXPORT 63 SCIP_RETCODE SCIPexprintCreate( 64 BMS_BLKMEM* blkmem, /**< block memory data structure */ 65 SCIP_EXPRINT** exprint /**< buffer to store pointer to expression interpreter */ 66 ); 67 68 /** frees an expression interpreter object */ 69 SCIP_EXPORT 70 SCIP_RETCODE SCIPexprintFree( 71 SCIP_EXPRINT** exprint /**< expression interpreter that should be freed */ 72 ); 73 74 /** compiles an expression tree and stores compiled data in expression tree */ 75 SCIP_EXPORT 76 SCIP_RETCODE SCIPexprintCompile( 77 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 78 SCIP_EXPRTREE* tree /**< expression tree */ 79 ); 80 81 /** gives the capability to evaluate an expression by the expression interpreter 82 * 83 * In cases of user-given expressions, higher order derivatives may not be available for the user-expression, 84 * even if the expression interpreter could handle these. This method allows to recognize that, e.g., the 85 * Hessian for an expression is not available because it contains a user expression that does not provide 86 * Hessians. 87 */ 88 SCIP_EXPORT 89 SCIP_EXPRINTCAPABILITY SCIPexprintGetExprtreeCapability( 90 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 91 SCIP_EXPRTREE* tree /**< expression tree */ 92 ); 93 94 /** frees interpreter data */ 95 SCIP_EXPORT 96 SCIP_RETCODE SCIPexprintFreeData( 97 SCIP_EXPRINTDATA** interpreterdata /**< interpreter data that should freed */ 98 ); 99 100 /** notify expression interpreter that a new parameterization is used 101 * this probably causes retaping by AD algorithms 102 */ 103 SCIP_EXPORT 104 SCIP_RETCODE SCIPexprintNewParametrization( 105 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 106 SCIP_EXPRTREE* tree /**< expression tree */ 107 ); 108 109 /** evaluates an expression tree */ 110 SCIP_EXPORT 111 SCIP_RETCODE SCIPexprintEval( 112 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 113 SCIP_EXPRTREE* tree, /**< expression tree */ 114 SCIP_Real* varvals, /**< values of variables */ 115 SCIP_Real* val /**< buffer to store value of expression */ 116 ); 117 118 /** evaluates an expression tree on intervals */ 119 SCIP_EXPORT 120 SCIP_RETCODE SCIPexprintEvalInt( 121 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 122 SCIP_EXPRTREE* tree, /**< expression tree */ 123 SCIP_Real infinity, /**< value for infinity */ 124 SCIP_INTERVAL* varvals, /**< interval values of variables */ 125 SCIP_INTERVAL* val /**< buffer to store interval value of expression */ 126 ); 127 128 /** computes value and gradient of an expression tree */ 129 SCIP_EXPORT 130 SCIP_RETCODE SCIPexprintGrad( 131 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 132 SCIP_EXPRTREE* tree, /**< expression tree */ 133 SCIP_Real* varvals, /**< values of variables, can be NULL if new_varvals is FALSE */ 134 SCIP_Bool new_varvals, /**< have variable values changed since last call to a point evaluation routine? */ 135 SCIP_Real* val, /**< buffer to store expression value */ 136 SCIP_Real* gradient /**< buffer to store expression gradient, need to have length at least SCIPexprtreeGetNVars(tree) */ 137 ); 138 139 /** computes interval value and interval gradient of an expression tree */ 140 SCIP_EXPORT 141 SCIP_RETCODE SCIPexprintGradInt( 142 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 143 SCIP_EXPRTREE* tree, /**< expression tree */ 144 SCIP_Real infinity, /**< value for infinity */ 145 SCIP_INTERVAL* varvals, /**< interval values of variables, can be NULL if new_varvals is FALSE */ 146 SCIP_Bool new_varvals, /**< have variable interval values changed since last call to an interval evaluation routine? */ 147 SCIP_INTERVAL* val, /**< buffer to store expression interval value */ 148 SCIP_INTERVAL* gradient /**< buffer to store expression interval gradient, need to have length at least SCIPexprtreeGetNVars(tree) */ 149 ); 150 151 /** gives sparsity pattern of hessian 152 * 153 * NOTE: this function might be replaced later by something nicer. 154 * Since the AD code might need to do a forward sweep, you should pass variable values in here. 155 */ 156 SCIP_EXPORT 157 SCIP_RETCODE SCIPexprintHessianSparsityDense( 158 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 159 SCIP_EXPRTREE* tree, /**< expression tree */ 160 SCIP_Real* varvals, /**< values of variables */ 161 SCIP_Bool* sparsity /**< buffer to store sparsity pattern of Hessian, sparsity[i+n*j] indicates whether entry (i,j) is nonzero in the hessian */ 162 ); 163 164 /** computes value and dense hessian of an expression tree 165 * 166 * The full hessian is computed (lower left and upper right triangle). 167 */ 168 SCIP_EXPORT 169 SCIP_RETCODE SCIPexprintHessianDense( 170 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 171 SCIP_EXPRTREE* tree, /**< expression tree */ 172 SCIP_Real* varvals, /**< values of variables, can be NULL if new_varvals is FALSE */ 173 SCIP_Bool new_varvals, /**< have variable values changed since last call to an evaluation routine? */ 174 SCIP_Real* val, /**< buffer to store function value */ 175 SCIP_Real* hessian /**< buffer to store hessian values, need to have size at least n*n */ 176 ); 177 178 /** @} */ 179 180 #ifdef __cplusplus 181 } 182 #endif 183 184 #endif /* __SCIP_EXPRINTERPRET_H__ */ 185