1    	/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
2    	/*                                                                           */
3    	/*                  This file is part of the program and library             */
4    	/*         SCIP --- Solving Constraint Integer Programs                      */
5    	/*                                                                           */
6    	/*  Copyright (c) 2002-2023 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
78   	SCIP_Real SCIPversion(
79   	   void
80   	   );
81   	
82   	/** returns SCIP major version
83   	 *
84   	 *  @return major SCIP version
85   	 */
86   	SCIP_EXPORT
87   	int SCIPmajorVersion(
88   	   void
89   	   );
90   	
91   	/** returns SCIP minor version
92   	 *
93   	 *  @return minor SCIP version
94   	 */
95   	SCIP_EXPORT
96   	int SCIPminorVersion(
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
133  	void SCIPprintBuildOptions(
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
165  	SCIP_RETCODE SCIPcreate(
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
191  	SCIP_RETCODE SCIPfree(
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
202  	SCIP_STAGE SCIPgetStage(
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
219  	SCIP_RETCODE SCIPprintStage(
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
231  	SCIP_STATUS SCIPgetStatus(
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
243  	SCIP_RETCODE SCIPprintStatus(
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
253  	SCIP_Bool SCIPisTransformed(
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
264  	SCIP_Bool SCIPisExactSolve(
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
281  	SCIP_Bool SCIPisPresolveFinished(
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
290  	SCIP_Bool SCIPhasPerformedPresolve(
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
299  	SCIP_Bool SCIPpressedCtrlC(
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
310  	SCIP_Bool SCIPisStopped(
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
325  	SCIP_RETCODE SCIPincludeExternalCodeInformation(
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
333  	char** SCIPgetExternalCodeNames(
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
342  	char** SCIPgetExternalCodeDescriptions(
343  	   SCIP*                 scip                /**< SCIP data structure */
344  	   );
345  	
346  	/** returns the number of currently included information on external codes */
347  	SCIP_EXPORT
348  	int SCIPgetNExternalCodes(
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
357  	void SCIPprintExternalCodes(
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
380