Scippy

SCIP

Solving Constraint Integer Programs

exprinterpret.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-2024 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"
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
68 
69 /** creates an expression interpreter object */
70 SCIP_EXPORT
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
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
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
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
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
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
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
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
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__ */
const char * SCIPexprintGetName(void)
SCIP_RETCODE SCIPexprintCompile(SCIP *scip, SCIP_EXPRINT *exprint, SCIP_EXPR *expr, SCIP_EXPRINTDATA **exprintdata)
SCIP_RETCODE SCIPexprintFreeData(SCIP *scip, SCIP_EXPRINT *exprint, SCIP_EXPR *expr, SCIP_EXPRINTDATA **exprintdata)
type definitions for expression interpreter
SCIP_RETCODE SCIPexprintHessianSparsity(SCIP *scip, SCIP_EXPRINT *exprint, SCIP_EXPR *expr, SCIP_EXPRINTDATA *exprintdata, SCIP_Real *varvals, int **rowidxs, int **colidxs, int *nnz)
enum SCIP_Retcode SCIP_RETCODE
Definition: type_retcode.h:63
const char * SCIPexprintGetDesc(void)
SCIP_RETCODE SCIPexprintGrad(SCIP *scip, SCIP_EXPRINT *exprint, SCIP_EXPR *expr, SCIP_EXPRINTDATA *exprintdata, SCIP_Real *varvals, SCIP_Bool new_varvals, SCIP_Real *val, SCIP_Real *gradient)
unsigned int SCIP_EXPRINTCAPABILITY
type definitions for SCIP&#39;s main datastructure
SCIP_RETCODE SCIPexprintCreate(SCIP *scip, SCIP_EXPRINT **exprint)
SCIP_EXPRINTCAPABILITY SCIPexprintGetCapability(void)
SCIP_RETCODE SCIPexprintEval(SCIP *scip, SCIP_EXPRINT *exprint, SCIP_EXPR *expr, SCIP_EXPRINTDATA *exprintdata, SCIP_Real *varvals, SCIP_Real *val)
SCIP_EXPRINTCAPABILITY SCIPexprintGetExprCapability(SCIP *scip, SCIP_EXPRINT *exprint, SCIP_EXPR *expr, SCIP_EXPRINTDATA *exprintdata)
#define SCIP_Bool
Definition: def.h:91
SCIP_RETCODE SCIPexprintFree(SCIP *scip, SCIP_EXPRINT **exprint)
struct SCIP_ExprInt SCIP_EXPRINT
SCIP_RETCODE SCIPexprintHessian(SCIP *scip, SCIP_EXPRINT *exprint, SCIP_EXPR *expr, SCIP_EXPRINTDATA *exprintdata, SCIP_Real *varvals, SCIP_Bool new_varvals, SCIP_Real *val, int **rowidxs, int **colidxs, SCIP_Real **hessianvals, int *nnz)
type and macro definitions related to algebraic expressions
#define SCIP_Real
Definition: def.h:173
common defines and data types used in all packages of SCIP
struct SCIP_ExprIntData SCIP_EXPRINTDATA