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