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 exprinterpret.h 26 * @brief methods to interpret (evaluate) an expression "fast" 27 * @ingroup EXPRINTS 28 * @author Stefan Vigerske 29 * 30 * Realized similar to LPI: one implementation of an interpreter is linked in. 31 */ 32 33 /* @todo product Gradient times vector 34 @todo product Hessian times vector 35 @todo product Hessian of Lagrangian times vector? 36 @todo sparse Hessian of Lagrangian (sets of expressions)? 37 */ 38 39 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/ 40 41 #ifndef __SCIP_EXPRINTERPRET_H__ 42 #define __SCIP_EXPRINTERPRET_H__ 43 44 #include "scip/def.h" 45 #include "scip/type_exprinterpret.h" 46 #include "scip/type_scip.h" 47 #include "scip/type_expr.h" 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 /**@addtogroup EXPRINTS 54 * @{ 55 */ 56 57 /** gets name and version of expression interpreter */ 58 SCIP_EXPORT 59 const char* SCIPexprintGetName(void); 60 61 /** gets descriptive text of expression interpreter */ 62 SCIP_EXPORT 63 const char* SCIPexprintGetDesc(void); 64 65 /** gets capabilities of expression interpreter (using bitflags) */ 66 SCIP_EXPORT 67 SCIP_EXPRINTCAPABILITY SCIPexprintGetCapability(void); 68 69 /** creates an expression interpreter object */ 70 SCIP_EXPORT 71 SCIP_RETCODE SCIPexprintCreate( 72 SCIP* scip, /**< SCIP data structure */ 73 SCIP_EXPRINT** exprint /**< buffer to store pointer to expression interpreter */ 74 ); 75 76 /** frees an expression interpreter object */ 77 SCIP_EXPORT 78 SCIP_RETCODE SCIPexprintFree( 79 SCIP* scip, /**< SCIP data structure */ 80 SCIP_EXPRINT** exprint /**< expression interpreter that should be freed */ 81 ); 82 83 /** compiles an expression and returns interpreter-specific data for expression 84 * 85 * can be called again with existing exprintdata if expression has been changed 86 * 87 * @attention *exprintdata needs to be initialized to NULL at first call 88 * @attention the expression is assumed to use varidx expressions instead of var expressions 89 */ 90 SCIP_EXPORT 91 SCIP_RETCODE SCIPexprintCompile( 92 SCIP* scip, /**< SCIP data structure */ 93 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 94 SCIP_EXPR* expr, /**< expression */ 95 SCIP_EXPRINTDATA** exprintdata /**< buffer to store pointer to compiled data */ 96 ); 97 98 /** frees interpreter data for expression */ 99 SCIP_EXPORT 100 SCIP_RETCODE SCIPexprintFreeData( 101 SCIP* scip, /**< SCIP data structure */ 102 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 103 SCIP_EXPR* expr, /**< expression */ 104 SCIP_EXPRINTDATA** exprintdata /**< pointer to pointer to compiled data to be freed */ 105 ); 106 107 /** gives the capability to evaluate an expression by the expression interpreter 108 * 109 * In cases of user-given expressions, higher order derivatives may not be available for the user-expression, 110 * even if the expression interpreter could handle these. This method allows to recognize that, e.g., the 111 * Hessian for an expression is not available because it contains a user expression that does not provide 112 * Hessians. 113 */ 114 SCIP_EXPORT 115 SCIP_EXPRINTCAPABILITY SCIPexprintGetExprCapability( 116 SCIP* scip, /**< SCIP data structure */ 117 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 118 SCIP_EXPR* expr, /**< expression */ 119 SCIP_EXPRINTDATA* exprintdata /**< interpreter-specific data for expression */ 120 ); 121 122 /** evaluates an expression */ 123 SCIP_EXPORT 124 SCIP_RETCODE SCIPexprintEval( 125 SCIP* scip, /**< SCIP data structure */ 126 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 127 SCIP_EXPR* expr, /**< expression */ 128 SCIP_EXPRINTDATA* exprintdata, /**< interpreter-specific data for expression */ 129 SCIP_Real* varvals, /**< values of variables */ 130 SCIP_Real* val /**< buffer to store value of expression */ 131 ); 132 133 /** computes value and gradient of an expression */ 134 SCIP_EXPORT 135 SCIP_RETCODE SCIPexprintGrad( 136 SCIP* scip, /**< SCIP data structure */ 137 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 138 SCIP_EXPR* expr, /**< expression */ 139 SCIP_EXPRINTDATA* exprintdata, /**< interpreter-specific data for expression */ 140 SCIP_Real* varvals, /**< values of variables, can be NULL if new_varvals is FALSE */ 141 SCIP_Bool new_varvals, /**< have variable values changed since last call to a point evaluation routine? */ 142 SCIP_Real* val, /**< buffer to store expression value */ 143 SCIP_Real* gradient /**< buffer to store expression gradient */ 144 ); 145 146 /** gives sparsity pattern of lower-triangular part of Hessian 147 * 148 * Since the AD code might need to do a forward sweep, variable values need to be passed in here. 149 * 150 * Result will have `(*colidxs)[i] <= (*rowidixs)[i]` for `i=0..*nnz`. 151 */ 152 SCIP_EXPORT 153 SCIP_RETCODE SCIPexprintHessianSparsity( 154 SCIP* scip, /**< SCIP data structure */ 155 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 156 SCIP_EXPR* expr, /**< expression */ 157 SCIP_EXPRINTDATA* exprintdata, /**< interpreter-specific data for expression */ 158 SCIP_Real* varvals, /**< values of variables */ 159 int** rowidxs, /**< buffer to return array with row indices of Hessian elements */ 160 int** colidxs, /**< buffer to return array with column indices of Hessian elements */ 161 int* nnz /**< buffer to return length of arrays */ 162 ); 163 164 /** computes value and Hessian of an expression 165 * 166 * Returned arrays `rowidxs` and `colidxs` and number of elements `nnz` are the same as given by SCIPexprintHessianSparsity(). 167 * Returned array `hessianvals` will contain the corresponding Hessian elements. 168 */ 169 SCIP_EXPORT 170 SCIP_RETCODE SCIPexprintHessian( 171 SCIP* scip, /**< SCIP data structure */ 172 SCIP_EXPRINT* exprint, /**< interpreter data structure */ 173 SCIP_EXPR* expr, /**< expression */ 174 SCIP_EXPRINTDATA* exprintdata, /**< interpreter-specific data for expression */ 175 SCIP_Real* varvals, /**< values of variables, can be NULL if new_varvals is FALSE */ 176 SCIP_Bool new_varvals, /**< have variable values changed since last call to an evaluation routine? */ 177 SCIP_Real* val, /**< buffer to store function value */ 178 int** rowidxs, /**< buffer to return array with row indices of Hessian elements */ 179 int** colidxs, /**< buffer to return array with column indices of Hessian elements */ 180 SCIP_Real** hessianvals, /**< buffer to return array with Hessian elements */ 181 int* nnz /**< buffer to return length of arrays */ 182 ); 183 184 /** @} */ 185 186 #ifdef __cplusplus 187 } 188 #endif 189 190 #endif /* __SCIP_EXPRINTERPRET_H__ */ 191