Scippy

SCIP

Solving Constraint Integer Programs

scip_nlpi.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 2002-2022 Zuse Institute Berlin */
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 scip_nlpi.h
26  * @ingroup PUBLICCOREAPI
27  * @brief public methods for NLPI solver interfaces
28  * @author Stefan Vigerske
29  * @author Thorsten Gellermann
30  */
31 
32 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
33 
34 #ifndef __SCIP_SCIP_NLPI_H__
35 #define __SCIP_SCIP_NLPI_H__
36 
37 #include "scip/type_nlpi.h"
38 #include "scip/type_misc.h"
39 #include "scip/type_lp.h"
40 #include "blockmemshell/memory.h"
41 #include "scip/pub_nlpi.h"
42 
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46 
47 /**@addtogroup PublicNLPIInterfaceMethods
48  *
49  * @{
50  */
51 
52 /** creates an NLPI and includes it into SCIP */
53 SCIP_EXPORT
55  SCIP* scip, /**< SCIP data structure */
56  const char* name, /**< name of NLP interface */
57  const char* description, /**< description of NLP interface */
58  int priority, /**< priority of NLP interface */
59  SCIP_DECL_NLPICOPY ((*nlpicopy)), /**< copying an NLPI, can be NULL */
60  SCIP_DECL_NLPIFREE ((*nlpifree)), /**< free NLPI user data */
61  SCIP_DECL_NLPIGETSOLVERPOINTER ((*nlpigetsolverpointer)), /**< get solver pointer, can be NULL */
62  SCIP_DECL_NLPICREATEPROBLEM ((*nlpicreateproblem)), /**< create a new problem instance */
63  SCIP_DECL_NLPIFREEPROBLEM ((*nlpifreeproblem)), /**< free a problem instance */
64  SCIP_DECL_NLPIGETPROBLEMPOINTER ((*nlpigetproblempointer)), /**< get problem pointer, can be NULL */
65  SCIP_DECL_NLPIADDVARS ((*nlpiaddvars)), /**< add variables */
66  SCIP_DECL_NLPIADDCONSTRAINTS ((*nlpiaddconstraints)), /**< add constraints */
67  SCIP_DECL_NLPISETOBJECTIVE ((*nlpisetobjective)), /**< set objective */
68  SCIP_DECL_NLPICHGVARBOUNDS ((*nlpichgvarbounds)), /**< change variable bounds */
69  SCIP_DECL_NLPICHGCONSSIDES ((*nlpichgconssides)), /**< change constraint sides */
70  SCIP_DECL_NLPIDELVARSET ((*nlpidelvarset)), /**< delete a set of constraints */
71  SCIP_DECL_NLPIDELCONSSET ((*nlpidelconsset)), /**< delete a set of constraints */
72  SCIP_DECL_NLPICHGLINEARCOEFS ((*nlpichglinearcoefs)), /**< change coefficients in linear part of a constraint or objective */
73  SCIP_DECL_NLPICHGEXPR ((*nlpichgexpr)), /**< change nonlinear expression a constraint or objective */
74  SCIP_DECL_NLPICHGOBJCONSTANT ((*nlpichgobjconstant)), /**< change the constant offset in the objective */
75  SCIP_DECL_NLPISETINITIALGUESS ((*nlpisetinitialguess)), /**< set initial guess, can be NULL */
76  SCIP_DECL_NLPISOLVE ((*nlpisolve)), /**< solve NLP */
77  SCIP_DECL_NLPIGETSOLSTAT ((*nlpigetsolstat)), /**< get solution status */
78  SCIP_DECL_NLPIGETTERMSTAT ((*nlpigettermstat)), /**< get termination status */
79  SCIP_DECL_NLPIGETSOLUTION ((*nlpigetsolution)), /**< get solution */
80  SCIP_DECL_NLPIGETSTATISTICS ((*nlpigetstatistics)), /**< get solve statistics */
81  SCIP_NLPIDATA* nlpidata /**< NLP interface local data */
82  );
83 
84 /** returns the NLPI of the given name, or NULL if not existing */
85 SCIP_EXPORT
87  SCIP* scip, /**< SCIP data structure */
88  const char* name /**< name of NLPI */
89  );
90 
91 /** returns the array of currently available NLPIs (sorted by priority) */
92 SCIP_EXPORT
94  SCIP* scip /**< SCIP data structure */
95  );
96 
97 /** returns the number of currently available NLPIs */
98 SCIP_EXPORT
99 int SCIPgetNNlpis(
100  SCIP* scip /**< SCIP data structure */
101  );
102 
103 /** sets the priority of an NLPI */
104 SCIP_EXPORT
106  SCIP* scip, /**< SCIP data structure */
107  SCIP_NLPI* nlpi, /**< NLPI */
108  int priority /**< new priority of the NLPI */
109  );
110 
111 /** gets internal pointer to NLP solver
112  *
113  * Depending on the solver interface, a solver pointer may exist for every NLP problem instance.
114  * For this case, a NLPI problem can be passed in as well.
115  */
116 SCIP_EXPORT
117 SCIP_DECL_NLPIGETSOLVERPOINTER(SCIPgetNlpiSolverPointer);
118 
119 /** creates an empty problem instance */
120 SCIP_EXPORT
121 SCIP_DECL_NLPICREATEPROBLEM(SCIPcreateNlpiProblem);
122 
123 /** frees a problem instance */
124 SCIP_EXPORT
125 SCIP_DECL_NLPIFREEPROBLEM(SCIPfreeNlpiProblem);
126 
127 /** gets internal pointer to solver-internal problem instance */
128 SCIP_EXPORT
129 SCIP_DECL_NLPIGETPROBLEMPOINTER(SCIPgetNlpiProblemPointer);
130 
131 /** add variables to nlpi */
132 SCIP_EXPORT
133 SCIP_DECL_NLPIADDVARS(SCIPaddNlpiVars);
134 
135 /** add constraints to nlpi */
136 SCIP_EXPORT
137 SCIP_DECL_NLPIADDCONSTRAINTS(SCIPaddNlpiConstraints);
138 
139 /** sets or overwrites objective, a minimization problem is expected */
140 SCIP_EXPORT
141 SCIP_DECL_NLPISETOBJECTIVE(SCIPsetNlpiObjective);
142 
143 /** change variable bounds */
144 SCIP_EXPORT
145 SCIP_DECL_NLPICHGVARBOUNDS(SCIPchgNlpiVarBounds);
146 
147 /** change constraint sides */
148 SCIP_EXPORT
149 SCIP_DECL_NLPICHGCONSSIDES(SCIPchgNlpiConsSides);
150 
151 /** delete a set of variables */
152 SCIP_EXPORT
153 SCIP_DECL_NLPIDELVARSET(SCIPdelNlpiVarSet);
154 
155 /** delete a set of constraints */
156 SCIP_EXPORT
157 SCIP_DECL_NLPIDELCONSSET(SCIPdelNlpiConsSet);
158 
159 /** changes or adds linear coefficients in a constraint or objective */
160 SCIP_EXPORT
161 SCIP_DECL_NLPICHGLINEARCOEFS(SCIPchgNlpiLinearCoefs);
162 
163 /** change the expression in the nonlinear part */
164 SCIP_EXPORT
165 SCIP_DECL_NLPICHGEXPR(SCIPchgNlpiExpr);
166 
167 /** change the constant offset in the objective */
168 SCIP_EXPORT
169 SCIP_DECL_NLPICHGOBJCONSTANT(SCIPchgNlpiObjConstant);
170 
171 /** sets initial guess */
172 SCIP_EXPORT
173 SCIP_DECL_NLPISETINITIALGUESS(SCIPsetNlpiInitialGuess);
174 
175 /** try to solve NLP with all parameters given as SCIP_NLPPARAM struct
176  *
177  * Typical use is
178  *
179  * SCIP_NLPPARAM nlparam = { SCIP_NLPPARAM_DEFAULT(scip); }
180  * nlpparam.iterlimit = 42;
181  * SCIP_CALL( SCIPsolveNlpiParam(scip, nlpi, nlpiproblem, nlpparam) );
182  *
183  * or, in "one" line:
184  *
185  * SCIP_CALL( SCIPsolveNlpiParam(scip, nlpi, nlpiproblem,
186  * (SCIP_NLPPARAM){ SCIP_NLPPARAM_DEFAULT(scip), .iterlimit = 42 }) );
187  *
188  * To get the latter, also \ref SCIPsolveNlpi can be used.
189  */
190 SCIP_EXPORT
191 SCIP_DECL_NLPISOLVE(SCIPsolveNlpiParam);
192 
193 /** try to solve NLP with non-default parameters given as optional arguments
194  *
195  * Typical use is
196  *
197  * SCIP_CALL( SCIPsolveNlpi(scip, nlpi, nlpiproblem) );
198  *
199  * to solve with default parameters.
200  * Additionally, one or several values of SCIP_NLPPARAM can be set:
201  *
202  * SCIP_CALL( SCIPsolveNlpi(scip, nlpi, nlpiproblem, .iterlimit = 42, .verblevel = 1) ); //lint !e666
203  */
204 /* the problem argument has been made part of the variadic arguments, since ISO C99 requires at least one argument for the "..." part and we want to allow leaving all parameters at default
205  * for the same reason, we set the .caller argument, so that macro SCIP_VARARGS_REST will have at least one arg to return
206  */
207 #if !defined(_MSC_VER) || _MSC_VER >= 1800
208 #define SCIPsolveNlpi(scip, nlpi, ...) \
209  SCIPsolveNlpiParam(scip, nlpi, SCIP_VARARGS_FIRST((__VA_ARGS__, ignored)), \
210  (SCIP_NLPPARAM){ SCIP_NLPPARAM_DEFAULT_INITS(scip), SCIP_VARARGS_REST(__VA_ARGS__, .caller = __FILE__) })
211 #else
212 /* very old MSVC doesn't support C99's designated initializers, so have a version of SCIPsolveNlpi() that just ignores given parameters
213  * (compilation of scip_nlpi.c will print a warning)
214  */
215 #define SCIPsolveNlpi(scip, nlpi, ...) \
216  SCIPsolveNlpiParam(scip, nlpi, SCIP_VARARGS_FIRST((__VA_ARGS__, ignored)), SCIP_NLPPARAM_DEFAULT_STATIC)
217 #endif
218 
219 /** gives solution status */
220 SCIP_EXPORT
221 SCIP_DECL_NLPIGETSOLSTAT(SCIPgetNlpiSolstat);
222 
223 /** gives termination reason */
224 SCIP_EXPORT
225 SCIP_DECL_NLPIGETTERMSTAT(SCIPgetNlpiTermstat);
226 
227 /** gives primal and dual solution
228  * for a ranged constraint, the dual variable is positive if the right hand side is active and negative if the left hand side is active
229  */
230 SCIP_EXPORT
231 SCIP_DECL_NLPIGETSOLUTION(SCIPgetNlpiSolution);
232 
233 /** gives solve statistics */
234 SCIP_EXPORT
235 SCIP_DECL_NLPIGETSTATISTICS(SCIPgetNlpiStatistics);
236 
237 
238 /**@name Convenience methods to setup and update an NLPI problem using NLROWS
239  *
240  * These methods can be used, for example, to create a NLPI problem that contains only the convex rows of the SCIP NLP relaxation.
241  * @{
242  */
243 
244 /** creates a NLPI problem from given nonlinear rows
245  *
246  * The function computes for each variable the number of non-linear occurrences and stores it in the nlscore array.
247  *
248  * @note the first row corresponds always to the cutoff row (even if cutoffbound is SCIPinfinity(scip))
249  **/
250 SCIP_EXPORT
252  SCIP* scip, /**< SCIP data structure */
253  SCIP_NLPI* nlpi, /**< interface to NLP solver */
254  SCIP_NLPIPROBLEM** nlpiprob, /**< buffer to store pointer to created nlpi problem */
255  const char* name, /**< name to give to problem */
256  SCIP_NLROW** nlrows, /**< nonlinear rows */
257  int nnlrows, /**< number of nonlinear rows */
258  SCIP_HASHMAP* var2idx, /**< empty hash map to store mapping between variables and indices in nlpiprob */
259  SCIP_HASHMAP* nlrow2idx, /**< empty hash map to store mapping between variables and indices in nlpiprob, can be NULL */
260  SCIP_Real* nlscore, /**< array to store the score of each nonlinear variable (NULL if not needed) */
261  SCIP_Real cutoffbound, /**< cutoff bound */
262  SCIP_Bool setobj, /**< whether the objective function should be set to one of the SCIP problem */
263  SCIP_Bool onlyconvex /**< filter only for convex constraints */
264  );
265 
266 /** updates variable bounds and the cutoff row in a NLPI problem
267  *
268  * The NLPI problem must have been setup by SCIPcreateNlpiProblemFromNlRows().
269  */
270 SCIP_EXPORT
272  SCIP* scip, /**< SCIP data structure */
273  SCIP_NLPI* nlpi, /**< interface to NLP solver */
274  SCIP_NLPIPROBLEM* nlpiprob, /**< nlpi problem representing the convex NLP relaxation */
275  SCIP_HASHMAP* var2nlpiidx, /**< mapping between variables and nlpi indices */
276  SCIP_VAR** nlpivars, /**< array containing all variables of the nlpi */
277  int nlpinvars, /**< total number of nlpi variables */
278  SCIP_Real cutoffbound /**< new cutoff bound */
279  );
280 
281 /** adds SCIP_ROWs to a NLPI problem */
282 SCIP_EXPORT
284  SCIP* scip, /**< SCIP data structure */
285  SCIP_NLPI* nlpi, /**< interface to NLP solver */
286  SCIP_NLPIPROBLEM* nlpiprob, /**< nlpi problem */
287  SCIP_HASHMAP* var2idx, /**< empty hash map to store mapping between variables and indices in nlpiprob */
288  SCIP_ROW** rows, /**< rows to add */
289  int nrows /**< number of rows to add */
290  );
291 
292 /** adds SCIP_NLROWs to a NLPI problem */
293 SCIP_EXPORT
295  SCIP* scip, /**< SCIP data structure */
296  SCIP_NLPI* nlpi, /**< interface to NLP solver */
297  SCIP_NLPIPROBLEM* nlpiprob, /**< nlpi problem */
298  SCIP_HASHMAP* var2idx, /**< empty hash map to store mapping between variables and indices in nlpiprob */
299  SCIP_NLROW** nlrows, /**< rows to add */
300  int nnlrows /**< number of rows to add */
301  );
302 
303 /** @} */
304 
305 /** @} */
306 
307 #ifdef __cplusplus
308 }
309 #endif
310 
311 #endif /* __SCIP_SCIP_NLPI_H__ */
SCIP_DECL_NLPICHGCONSSIDES(SCIPchgNlpiConsSides)
Definition: scip_nlpi.c:301
SCIP_DECL_NLPICHGEXPR(SCIPchgNlpiExpr)
Definition: scip_nlpi.c:341
SCIP_DECL_NLPISOLVE(SCIPsolveNlpiParam)
Definition: scip_nlpi.c:385
type definitions for miscellaneous datastructures
SCIP_NLPI * SCIPfindNlpi(SCIP *scip, const char *name)
Definition: scip_nlpi.c:173
SCIP_DECL_NLPICREATEPROBLEM(SCIPcreateNlpiProblem)
Definition: scip_nlpi.c:233
SCIP_DECL_NLPISETOBJECTIVE(SCIPsetNlpiObjective)
Definition: scip_nlpi.c:281
enum SCIP_Retcode SCIP_RETCODE
Definition: type_retcode.h:63
SCIP_DECL_NLPICHGVARBOUNDS(SCIPchgNlpiVarBounds)
Definition: scip_nlpi.c:291
SCIP_DECL_NLPISETINITIALGUESS(SCIPsetNlpiInitialGuess)
Definition: scip_nlpi.c:361
SCIP_DECL_NLPIGETSOLSTAT(SCIPgetNlpiSolstat)
Definition: scip_nlpi.c:400
SCIP_NLPI ** SCIPgetNlpis(SCIP *scip)
Definition: scip_nlpi.c:186
SCIP_DECL_NLPIGETSTATISTICS(SCIPgetNlpiStatistics)
Definition: scip_nlpi.c:428
type definitions for LP management
int SCIPgetNNlpis(SCIP *scip)
Definition: scip_nlpi.c:199
SCIP_DECL_NLPIADDCONSTRAINTS(SCIPaddNlpiConstraints)
Definition: scip_nlpi.c:271
struct SCIP_NlpiData SCIP_NLPIDATA
Definition: type_nlpi.h:52
SCIP_RETCODE SCIPupdateNlpiProblem(SCIP *scip, SCIP_NLPI *nlpi, SCIP_NLPIPROBLEM *nlpiprob, SCIP_HASHMAP *var2nlpiidx, SCIP_VAR **nlpivars, int nlpinvars, SCIP_Real cutoffbound)
Definition: scip_nlpi.c:729
#define SCIP_DECL_NLPICOPY(x)
Definition: type_nlpi.h:215
SCIP_DECL_NLPIGETSOLUTION(SCIPgetNlpiSolution)
Definition: scip_nlpi.c:418
SCIP_DECL_NLPIADDVARS(SCIPaddNlpiVars)
Definition: scip_nlpi.c:261
SCIP_DECL_NLPICHGLINEARCOEFS(SCIPchgNlpiLinearCoefs)
Definition: scip_nlpi.c:331
SCIP_DECL_NLPICHGOBJCONSTANT(SCIPchgNlpiObjConstant)
Definition: scip_nlpi.c:351
SCIP_RETCODE SCIPaddNlpiProblemRows(SCIP *scip, SCIP_NLPI *nlpi, SCIP_NLPIPROBLEM *nlpiprob, SCIP_HASHMAP *var2idx, SCIP_ROW **rows, int nrows)
Definition: scip_nlpi.c:781
#define SCIP_Bool
Definition: def.h:93
SCIP_DECL_NLPIDELVARSET(SCIPdelNlpiVarSet)
Definition: scip_nlpi.c:311
SCIP_RETCODE SCIPcreateNlpiProblemFromNlRows(SCIP *scip, SCIP_NLPI *nlpi, SCIP_NLPIPROBLEM **nlpiprob, const char *name, SCIP_NLROW **nlrows, int nnlrows, SCIP_HASHMAP *var2idx, SCIP_HASHMAP *nlrow2idx, SCIP_Real *nlscore, SCIP_Real cutoffbound, SCIP_Bool setobj, SCIP_Bool onlyconvex)
Definition: scip_nlpi.c:443
public methods for NLP solver interfaces
SCIP_DECL_NLPIDELCONSSET(SCIPdelNlpiConsSet)
Definition: scip_nlpi.c:321
SCIP_DECL_NLPIGETTERMSTAT(SCIPgetNlpiTermstat)
Definition: scip_nlpi.c:408
SCIP_DECL_NLPIFREEPROBLEM(SCIPfreeNlpiProblem)
Definition: scip_nlpi.c:243
SCIP_RETCODE SCIPsetNlpiPriority(SCIP *scip, SCIP_NLPI *nlpi, int priority)
Definition: scip_nlpi.c:210
#define SCIP_DECL_NLPIFREE(x)
Definition: type_nlpi.h:225
#define SCIP_Real
Definition: def.h:186
SCIP_RETCODE SCIPaddNlpiProblemNlRows(SCIP *scip, SCIP_NLPI *nlpi, SCIP_NLPIPROBLEM *nlpiprob, SCIP_HASHMAP *var2idx, SCIP_NLROW **nlrows, int nnlrows)
Definition: scip_nlpi.c:864
SCIP_RETCODE SCIPincludeNlpi(SCIP *scip, const char *name, const char *description, int priority, SCIP_DECL_NLPICOPY((*nlpicopy)), SCIP_DECL_NLPIFREE((*nlpifree)), SCIP_DECL_NLPIGETSOLVERPOINTER((*nlpigetsolverpointer)), SCIP_DECL_NLPICREATEPROBLEM((*nlpicreateproblem)), SCIP_DECL_NLPIFREEPROBLEM((*nlpifreeproblem)), SCIP_DECL_NLPIGETPROBLEMPOINTER((*nlpigetproblempointer)), SCIP_DECL_NLPIADDVARS((*nlpiaddvars)), SCIP_DECL_NLPIADDCONSTRAINTS((*nlpiaddconstraints)), SCIP_DECL_NLPISETOBJECTIVE((*nlpisetobjective)), SCIP_DECL_NLPICHGVARBOUNDS((*nlpichgvarbounds)), SCIP_DECL_NLPICHGCONSSIDES((*nlpichgconssides)), SCIP_DECL_NLPIDELVARSET((*nlpidelvarset)), SCIP_DECL_NLPIDELCONSSET((*nlpidelconsset)), SCIP_DECL_NLPICHGLINEARCOEFS((*nlpichglinearcoefs)), SCIP_DECL_NLPICHGEXPR((*nlpichgexpr)), SCIP_DECL_NLPICHGOBJCONSTANT((*nlpichgobjconstant)), SCIP_DECL_NLPISETINITIALGUESS((*nlpisetinitialguess)), SCIP_DECL_NLPISOLVE((*nlpisolve)), SCIP_DECL_NLPIGETSOLSTAT((*nlpigetsolstat)), SCIP_DECL_NLPIGETTERMSTAT((*nlpigettermstat)), SCIP_DECL_NLPIGETSOLUTION((*nlpigetsolution)), SCIP_DECL_NLPIGETSTATISTICS((*nlpigetstatistics)), SCIP_NLPIDATA *nlpidata)
Definition: scip_nlpi.c:107
SCIP_DECL_NLPIGETSOLVERPOINTER(SCIPgetNlpiSolverPointer)
Definition: scip_nlpi.c:225
SCIP_DECL_NLPIGETPROBLEMPOINTER(SCIPgetNlpiProblemPointer)
Definition: scip_nlpi.c:253
type definitions for NLP solver interfaces
memory allocation routines