Scippy

SCIP

Solving Constraint Integer Programs

scip_general.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 scip_general.h
26  * @ingroup PUBLICCOREAPI
27  * @brief general public methods
28  * @author Tobias Achterberg
29  * @author Timo Berthold
30  * @author Thorsten Koch
31  * @author Alexander Martin
32  * @author Marc Pfetsch
33  * @author Kati Wolter
34  * @author Gregor Hendel
35  * @author Leona Gottwald
36  */
37 
38 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
39 
40 #ifndef __SCIP_SCIP_GENERAL_H__
41 #define __SCIP_SCIP_GENERAL_H__
42 
43 
44 #include "scip/def.h"
45 #include "scip/type_retcode.h"
46 #include "scip/type_scip.h"
47 #include "scip/type_set.h"
48 #include "scip/type_stat.h"
49 
50 /* In debug mode, we include the SCIP's structure in scip.c, such that no one can access
51  * this structure except the interface methods in scip.c.
52  * In optimized mode, the structure is included in scip.h, because some of the methods
53  * are implemented as defines for performance reasons (e.g. the numerical comparisons).
54  * Additionally, the internal "set.h" is included, such that the defines in set.h are
55  * available in optimized mode.
56  */
57 #ifdef NDEBUG
58 #include "scip/struct_scip.h"
59 #include "scip/struct_stat.h"
60 #include "scip/struct_set.h"
61 #include "scip/solve.h"
62 #endif
63 
64 #ifdef __cplusplus
65 extern "C" {
66 #endif
67 
68 /**@addtogroup MiscellaneousMethods
69  *
70  * @{
71  */
72 
73 /** returns complete SCIP version number in the format "major . minor tech"
74  *
75  * @return complete SCIP version
76  */
77 SCIP_EXPORT
79  void
80  );
81 
82 /** returns SCIP major version
83  *
84  * @return major SCIP version
85  */
86 SCIP_EXPORT
88  void
89  );
90 
91 /** returns SCIP minor version
92  *
93  * @return minor SCIP version
94  */
95 SCIP_EXPORT
97  void
98  );
99 
100 /** returns SCIP technical version
101  *
102  * @return technical SCIP version
103  */
104 SCIP_EXPORT
105 int SCIPtechVersion(
106  void
107  );
108 
109 /** returns SCIP sub version number
110  *
111  * @return subversion SCIP version
112  */
113 SCIP_EXPORT
114 int SCIPsubversion(
115  void
116  );
117 
118 /** prints a version information line to a file stream via the message handler system
119  *
120  * @note If the message handler is set to a NULL pointer nothing will be printed
121  */
122 SCIP_EXPORT
123 void SCIPprintVersion(
124  SCIP* scip, /**< SCIP data structure */
125  FILE* file /**< output file (or NULL for standard output) */
126  );
127 
128 /** prints detailed information on the compile-time flags
129  *
130  * @note If the message handler is set to a NULL pointer nothing will be printed
131  */
132 SCIP_EXPORT
134  SCIP* scip, /**< SCIP data structure */
135  FILE* file /**< output file (or NULL for standard output) */
136  );
137 
138 /** prints error message for the given SCIP_RETCODE via the error prints method */
139 SCIP_EXPORT
140 void SCIPprintError(
141  SCIP_RETCODE retcode /**< SCIP return code causing the error */
142  );
143 
144 /**@} */
145 
146 /**@addtogroup GeneralSCIPMethods
147  *
148  * @{
149  */
150 
151 /** creates and initializes SCIP data structures
152  *
153  * @note The SCIP default message handler is installed. Use the method SCIPsetMessagehdlr() to install your own
154  * message handler or SCIPsetMessagehdlrLogfile() and SCIPsetMessagehdlrQuiet() to write into a log
155  * file and turn off/on the display output, respectively.
156  *
157  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
158  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
159  *
160  * @post After calling this method @p scip reached the solving stage \ref SCIP_STAGE_INIT
161  *
162  * See \ref SCIP_Stage "SCIP_STAGE" for a complete list of all possible solving stages.
163  */
164 SCIP_EXPORT
166  SCIP** scip /**< pointer to SCIP data structure */
167  );
168 
169 /** frees SCIP data structures
170  *
171  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
172  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
173  *
174  * @pre This method can be called if @p scip is in one of the following stages:
175  * - \ref SCIP_STAGE_INIT
176  * - \ref SCIP_STAGE_PROBLEM
177  * - \ref SCIP_STAGE_TRANSFORMED
178  * - \ref SCIP_STAGE_INITPRESOLVE
179  * - \ref SCIP_STAGE_PRESOLVING
180  * - \ref SCIP_STAGE_PRESOLVED
181  * - \ref SCIP_STAGE_EXITPRESOLVE
182  * - \ref SCIP_STAGE_SOLVING
183  * - \ref SCIP_STAGE_SOLVED
184  * - \ref SCIP_STAGE_FREE
185  *
186  * @post After calling this method \SCIP reached the solving stage \ref SCIP_STAGE_FREE
187  *
188  * See \ref SCIP_Stage "SCIP_STAGE" for a complete list of all possible solving stages.
189  */
190 SCIP_EXPORT
192  SCIP** scip /**< pointer to SCIP data structure */
193  );
194 
195 /** returns current stage of SCIP
196  *
197  * @return the current SCIP stage
198  *
199  * See \ref SCIP_Stage "SCIP_STAGE" for a complete list of all possible solving stages.
200  */
201 SCIP_EXPORT
203  SCIP* scip /**< SCIP data structure */
204  );
205 
206 /** outputs SCIP stage and solution status if applicable via the message handler
207  *
208  * @note If the message handler is set to a NULL pointer nothing will be printed
209  *
210  * @note If limits have been changed between the solution and the call to this function, the status is recomputed and
211  * thus may to correspond to the original status.
212  *
213  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
214  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
215  *
216  * See \ref SCIP_Stage "SCIP_STAGE" for a complete list of all possible solving stages.
217  */
218 SCIP_EXPORT
220  SCIP* scip, /**< SCIP data structure */
221  FILE* file /**< output file (or NULL for standard output) */
222  );
223 
224 /** gets solution status
225  *
226  * @return SCIP solution status
227  *
228  * See \ref SCIP_Status "SCIP_STATUS" for a complete list of all possible solving status.
229  */
230 SCIP_EXPORT
232  SCIP* scip /**< SCIP data structure */
233  );
234 
235 /** outputs solution status
236  *
237  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
238  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
239  *
240  * See \ref SCIP_Status "SCIP_STATUS" for a complete list of all possible solving status.
241  */
242 SCIP_EXPORT
244  SCIP* scip, /**< SCIP data structure */
245  FILE* file /**< output file (or NULL for standard output) */
246  );
247 
248 /** returns whether the current stage belongs to the transformed problem space
249  *
250  * @return Returns TRUE if the \SCIP instance is transformed, otherwise FALSE
251  */
252 SCIP_EXPORT
254  SCIP* scip /**< SCIP data structure */
255  );
256 
257 /** returns whether the solution process is arithmetically exact, i.e., not subject to roundoff errors
258  *
259  * @note This feature is not supported yet!
260  *
261  * @return Returns TRUE if \SCIP is exact solving mode, otherwise FALSE
262  */
263 SCIP_EXPORT
265  SCIP* scip /**< SCIP data structure */
266  );
267 
268 /** returns whether the presolving process would be finished given no more presolving reductions are found in this
269  * presolving round
270  *
271  * Checks whether the number of presolving rounds is not exceeded and the presolving reductions found in the current
272  * presolving round suffice to trigger another presolving round.
273  *
274  * @note if subsequent presolvers find more reductions, presolving might continue even if the method returns FALSE
275  * @note does not check whether infeasibility or unboundedness was already detected in presolving (which would result
276  * in presolving being stopped although the method returns TRUE)
277  *
278  * @return Returns TRUE if presolving is finished if no further reductions are detected
279  */
280 SCIP_EXPORT
282  SCIP* scip /**< SCIP data structure */
283  );
284 
285 /** returns whether SCIP has performed presolving during the last solve
286  *
287  * @return Returns TRUE if presolving was performed during the last solve
288  */
289 SCIP_EXPORT
291  SCIP* scip /**< SCIP data structure */
292  );
293 
294 /** returns whether the user pressed CTRL-C to interrupt the solving process
295  *
296  * @return Returns TRUE if Ctrl-C was pressed, otherwise FALSE.
297  */
298 SCIP_EXPORT
300  SCIP* scip /**< SCIP data structure */
301  );
302 
303 /** returns whether the solving process should be / was stopped before proving optimality;
304  * if the solving process should be / was stopped, the status returned by SCIPgetStatus() yields
305  * the reason for the premature abort
306  *
307  * @return Returns TRUE if solving process is stopped/interrupted, otherwise FALSE.
308  */
309 SCIP_EXPORT
311  SCIP* scip /**< SCIP data structure */
312  );
313 
314 /**@} */
315 
316 /**@addtogroup PublicExternalCodeMethods
317  *
318  * @{
319  */
320 
321 
322 
323 /** includes information about an external code linked into the SCIP library */
324 SCIP_EXPORT
326  SCIP* scip, /**< SCIP data structure */
327  const char* name, /**< name of external code */
328  const char* description /**< description of external code, or NULL */
329  );
330 
331 /** returns an array of names of currently included external codes */
332 SCIP_EXPORT
334  SCIP* scip /**< SCIP data structure */
335  );
336 
337 /** returns an array of the descriptions of currently included external codes
338  *
339  * @note some descriptions may be NULL
340  */
341 SCIP_EXPORT
343  SCIP* scip /**< SCIP data structure */
344  );
345 
346 /** returns the number of currently included information on external codes */
347 SCIP_EXPORT
349  SCIP* scip /**< SCIP data structure */
350  );
351 
352 /** prints information on external codes to a file stream via the message handler system
353  *
354  * @note If the message handler is set to a NULL pointer nothing will be printed
355  */
356 SCIP_EXPORT
358  SCIP* scip, /**< SCIP data structure */
359  FILE* file /**< output file (or NULL for standard output) */
360  );
361 
362 /* In optimized mode, the function calls are overwritten by defines to reduce the number of function calls and
363  * speed up the algorithms.
364  */
365 #ifdef NDEBUG
366 
367 #define SCIPgetStage(scip) (((scip)->set)->stage)
368 #define SCIPhasPerformedPresolve(scip) ((scip)->stat->performpresol)
369 #define SCIPisStopped(scip) SCIPsolveIsStopped((scip)->set, (scip)->stat, 0)
370 
371 #endif
372 
373 /** @} */
374 
375 #ifdef __cplusplus
376 }
377 #endif
378 
379 #endif
SCIP_STAGE SCIPgetStage(SCIP *scip)
Definition: scip_general.c:380
char ** SCIPgetExternalCodeDescriptions(SCIP *scip)
Definition: scip_general.c:765
int SCIPmajorVersion(void)
Definition: scip_general.c:112
void SCIPprintExternalCodes(SCIP *scip, FILE *file)
Definition: scip_general.c:790
enum SCIP_Retcode SCIP_RETCODE
Definition: type_retcode.h:63
char ** SCIPgetExternalCodeNames(SCIP *scip)
Definition: scip_general.c:751
type definitions for global SCIP settings
type definitions for return codes for SCIP methods
SCIP_RETCODE SCIPcreate(SCIP **scip)
Definition: scip_general.c:307
SCIP_Bool SCIPisTransformed(SCIP *scip)
Definition: scip_general.c:596
SCIP_Bool SCIPpressedCtrlC(SCIP *scip)
Definition: scip_general.c:711
type definitions for problem statistics
SCIP_Bool SCIPisPresolveFinished(SCIP *scip)
Definition: scip_general.c:633
type definitions for SCIP&#39;s main datastructure
SCIP_STATUS SCIPgetStatus(SCIP *scip)
Definition: scip_general.c:498
SCIP_Real SCIPversion(void)
Definition: scip_general.c:101
SCIP_RETCODE SCIPprintStage(SCIP *scip, FILE *file)
Definition: scip_general.c:402
SCIP main data structure.
SCIP_RETCODE SCIPprintStatus(SCIP *scip, FILE *file)
Definition: scip_general.c:521
int SCIPgetNExternalCodes(SCIP *scip)
Definition: scip_general.c:776
#define SCIP_Bool
Definition: def.h:91
void SCIPprintVersion(SCIP *scip, FILE *file)
Definition: scip_general.c:156
enum SCIP_Status SCIP_STATUS
Definition: type_stat.h:67
int SCIPsubversion(void)
Definition: scip_general.c:145
int SCIPtechVersion(void)
Definition: scip_general.c:134
datastructures for problem statistics
internal methods for main solving loop and node processing
#define SCIP_Real
Definition: def.h:173
enum SCIP_Stage SCIP_STAGE
Definition: type_set.h:59
SCIP_Bool SCIPisStopped(SCIP *scip)
Definition: scip_general.c:724
SCIP_RETCODE SCIPincludeExternalCodeInformation(SCIP *scip, const char *name, const char *description)
Definition: scip_general.c:734
SCIP_Bool SCIPhasPerformedPresolve(SCIP *scip)
Definition: scip_general.c:695
common defines and data types used in all packages of SCIP
void SCIPprintError(SCIP_RETCODE retcode)
Definition: scip_general.c:221
int SCIPminorVersion(void)
Definition: scip_general.c:123
void SCIPprintBuildOptions(SCIP *scip, FILE *file)
Definition: scip_general.c:191
datastructures for global SCIP settings
SCIP_Bool SCIPisExactSolve(SCIP *scip)
Definition: scip_general.c:611
SCIP_RETCODE SCIPfree(SCIP **scip)
Definition: scip_general.c:339