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-2019 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 scip.zib.de. */
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"
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 extern
51 const char* SCIPexprintGetName(void);
52 
53 /** gets descriptive text of expression interpreter */
54 extern
55 const char* SCIPexprintGetDesc(void);
56 
57 /** gets capabilities of expression interpreter (using bitflags) */
58 extern
60 
61 /** creates an expression interpreter object */
62 extern
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 extern
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 extern
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 extern
90  SCIP_EXPRINT* exprint, /**< interpreter data structure */
91  SCIP_EXPRTREE* tree /**< expression tree */
92  );
93 
94 /** frees interpreter data */
95 extern
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 extern
105  SCIP_EXPRINT* exprint, /**< interpreter data structure */
106  SCIP_EXPRTREE* tree /**< expression tree */
107  );
108 
109 /** evaluates an expression tree */
110 extern
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 extern
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 extern
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 extern
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 extern
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 extern
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__ */
const char * SCIPexprintGetName(void)
#define infinity
Definition: gastrans.c:71
SCIP_RETCODE SCIPexprintGradInt(SCIP_EXPRINT *exprint, SCIP_EXPRTREE *tree, SCIP_Real infinity, SCIP_INTERVAL *varvals, SCIP_Bool new_varvals, SCIP_INTERVAL *val, SCIP_INTERVAL *gradient)
type definitions for expression interpreter
enum SCIP_Retcode SCIP_RETCODE
Definition: type_retcode.h:53
SCIP_RETCODE SCIPexprintCompile(SCIP_EXPRINT *exprint, SCIP_EXPRTREE *tree)
const char * SCIPexprintGetDesc(void)
SCIP_EXPRINTCAPABILITY SCIPexprintGetExprtreeCapability(SCIP_EXPRINT *exprint, SCIP_EXPRTREE *tree)
unsigned int SCIP_EXPRINTCAPABILITY
SCIP_RETCODE SCIPexprintEval(SCIP_EXPRINT *exprint, SCIP_EXPRTREE *tree, SCIP_Real *varvals, SCIP_Real *val)
interval arithmetics for provable bounds
SCIP_RETCODE SCIPexprintCreate(BMS_BLKMEM *blkmem, SCIP_EXPRINT **exprint)
SCIP_EXPRINTCAPABILITY SCIPexprintGetCapability(void)
#define SCIP_Bool
Definition: def.h:69
SCIP_RETCODE SCIPexprintNewParametrization(SCIP_EXPRINT *exprint, SCIP_EXPRTREE *tree)
SCIP_RETCODE SCIPexprintEvalInt(SCIP_EXPRINT *exprint, SCIP_EXPRTREE *tree, SCIP_Real infinity, SCIP_INTERVAL *varvals, SCIP_INTERVAL *val)
SCIP_RETCODE SCIPexprintHessianDense(SCIP_EXPRINT *exprint, SCIP_EXPRTREE *tree, SCIP_Real *varvals, SCIP_Bool new_varvals, SCIP_Real *val, SCIP_Real *hessian)
SCIP_RETCODE SCIPexprintGrad(SCIP_EXPRINT *exprint, SCIP_EXPRTREE *tree, SCIP_Real *varvals, SCIP_Bool new_varvals, SCIP_Real *val, SCIP_Real *gradient)
type definitions for expressions and expression trees
#define SCIP_Real
Definition: def.h:157
SCIP_RETCODE SCIPexprintHessianSparsityDense(SCIP_EXPRINT *exprint, SCIP_EXPRTREE *tree, SCIP_Real *varvals, SCIP_Bool *sparsity)
SCIP_RETCODE SCIPexprintFreeData(SCIP_EXPRINTDATA **interpreterdata)
SCIP_RETCODE SCIPexprintFree(SCIP_EXPRINT **exprint)
common defines and data types used in all packages of SCIP
struct BMS_BlkMem BMS_BLKMEM
Definition: memory.h:426
struct SCIP_ExprIntData SCIP_EXPRINTDATA
memory allocation routines