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