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_heur.h 26 * @ingroup PUBLICCOREAPI 27 * @brief public methods for primal heuristic plugins and divesets 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_HEUR_H__ 41 #define __SCIP_SCIP_HEUR_H__ 42 43 44 #include "scip/def.h" 45 #include "scip/type_heur.h" 46 #include "scip/type_result.h" 47 #include "scip/type_retcode.h" 48 #include "scip/type_scip.h" 49 #include "scip/type_timing.h" 50 #include "scip/type_var.h" 51 52 #ifdef __cplusplus 53 extern "C" { 54 #endif 55 56 /**@addtogroup PublicHeuristicMethods 57 * 58 * @{ 59 */ 60 61 /** creates a primal heuristic and includes it in SCIP. 62 * 63 * @note method has all heuristic callbacks as arguments and is thus changed every time a new 64 * callback is added in future releases; consider using SCIPincludeHeurBasic() and setter functions 65 * if you seek for a method which is less likely to change in future releases 66 * 67 * @return \ref SCIP_OKAY is returned if everything worked. otherwise a suitable error code is passed. see \ref 68 * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes. 69 * 70 * @pre This method can be called if @p scip is in one of the following stages: 71 * - \ref SCIP_STAGE_INIT 72 * - \ref SCIP_STAGE_PROBLEM 73 */ 74 SCIP_EXPORT 75 SCIP_RETCODE SCIPincludeHeur( 76 SCIP* scip, /**< SCIP data structure */ 77 const char* name, /**< name of primal heuristic */ 78 const char* desc, /**< description of primal heuristic */ 79 char dispchar, /**< display character of primal heuristic */ 80 int priority, /**< priority of the primal heuristic */ 81 int freq, /**< frequency for calling primal heuristic */ 82 int freqofs, /**< frequency offset for calling primal heuristic */ 83 int maxdepth, /**< maximal depth level to call heuristic at (-1: no limit) */ 84 SCIP_HEURTIMING timingmask, /**< positions in the node solving loop where heuristic should be executed; 85 * see definition of SCIP_HEURTIMING for possible values */ 86 SCIP_Bool usessubscip, /**< does the heuristic use a secondary SCIP instance? */ 87 SCIP_DECL_HEURCOPY ((*heurcopy)), /**< copy method of primal heuristic or NULL if you don't want to copy your plugin into sub-SCIPs */ 88 SCIP_DECL_HEURFREE ((*heurfree)), /**< destructor of primal heuristic */ 89 SCIP_DECL_HEURINIT ((*heurinit)), /**< initialize primal heuristic */ 90 SCIP_DECL_HEUREXIT ((*heurexit)), /**< deinitialize primal heuristic */ 91 SCIP_DECL_HEURINITSOL ((*heurinitsol)), /**< solving process initialization method of primal heuristic */ 92 SCIP_DECL_HEUREXITSOL ((*heurexitsol)), /**< solving process deinitialization method of primal heuristic */ 93 SCIP_DECL_HEUREXEC ((*heurexec)), /**< execution method of primal heuristic */ 94 SCIP_HEURDATA* heurdata /**< primal heuristic data */ 95 ); 96 97 /** creates a primal heuristic and includes it in SCIP with its most fundamental callbacks. 98 * All non-fundamental (or optional) callbacks 99 * as, e. g., init and exit callbacks, will be set to NULL. 100 * Optional callbacks can be set via specific setter functions, see SCIPsetHeurCopy(), SCIPsetHeurFree(), 101 * SCIPsetHeurInit(), SCIPsetHeurExit(), SCIPsetHeurInitsol(), and SCIPsetHeurExitsol() 102 * 103 * @note if you want to set all callbacks with a single method call, consider using SCIPincludeHeur() instead 104 */ 105 SCIP_EXPORT 106 SCIP_RETCODE SCIPincludeHeurBasic( 107 SCIP* scip, /**< SCIP data structure */ 108 SCIP_HEUR** heur, /**< pointer to the heuristic */ 109 const char* name, /**< name of primal heuristic */ 110 const char* desc, /**< description of primal heuristic */ 111 char dispchar, /**< display character of primal heuristic */ 112 int priority, /**< priority of the primal heuristic */ 113 int freq, /**< frequency for calling primal heuristic */ 114 int freqofs, /**< frequency offset for calling primal heuristic */ 115 int maxdepth, /**< maximal depth level to call heuristic at (-1: no limit) */ 116 SCIP_HEURTIMING timingmask, /**< positions in the node solving loop where heuristic should be executed; 117 * see definition of SCIP_HEURTIMING for possible values */ 118 SCIP_Bool usessubscip, /**< does the heuristic use a secondary SCIP instance? */ 119 SCIP_DECL_HEUREXEC ((*heurexec)), /**< execution method of primal heuristic */ 120 SCIP_HEURDATA* heurdata /**< primal heuristic data */ 121 ); 122 123 /** sets copy method of primal heuristic */ 124 SCIP_EXPORT 125 SCIP_RETCODE SCIPsetHeurCopy( 126 SCIP* scip, /**< SCIP data structure */ 127 SCIP_HEUR* heur, /**< primal heuristic */ 128 SCIP_DECL_HEURCOPY ((*heurcopy)) /**< copy method of primal heuristic or NULL if you don't want to copy your plugin into sub-SCIPs */ 129 ); 130 131 /** sets destructor method of primal heuristic */ 132 SCIP_EXPORT 133 SCIP_RETCODE SCIPsetHeurFree( 134 SCIP* scip, /**< SCIP data structure */ 135 SCIP_HEUR* heur, /**< primal heuristic */ 136 SCIP_DECL_HEURFREE ((*heurfree)) /**< destructor of primal heuristic */ 137 ); 138 139 /** sets initialization method of primal heuristic */ 140 SCIP_EXPORT 141 SCIP_RETCODE SCIPsetHeurInit( 142 SCIP* scip, /**< SCIP data structure */ 143 SCIP_HEUR* heur, /**< primal heuristic */ 144 SCIP_DECL_HEURINIT ((*heurinit)) /**< initialize primal heuristic */ 145 ); 146 147 /** sets deinitialization method of primal heuristic */ 148 SCIP_EXPORT 149 SCIP_RETCODE SCIPsetHeurExit( 150 SCIP* scip, /**< SCIP data structure */ 151 SCIP_HEUR* heur, /**< primal heuristic */ 152 SCIP_DECL_HEUREXIT ((*heurexit)) /**< deinitialize primal heuristic */ 153 ); 154 155 /** sets solving process initialization method of primal heuristic */ 156 SCIP_EXPORT 157 SCIP_RETCODE SCIPsetHeurInitsol( 158 SCIP* scip, /**< SCIP data structure */ 159 SCIP_HEUR* heur, /**< primal heuristic */ 160 SCIP_DECL_HEURINITSOL ((*heurinitsol)) /**< solving process initialization method of primal heuristic */ 161 ); 162 163 /** sets solving process deinitialization method of primal heuristic */ 164 SCIP_EXPORT 165 SCIP_RETCODE SCIPsetHeurExitsol( 166 SCIP* scip, /**< SCIP data structure */ 167 SCIP_HEUR* heur, /**< primal heuristic */ 168 SCIP_DECL_HEUREXITSOL ((*heurexitsol)) /**< solving process deinitialization method of primal heuristic */ 169 ); 170 171 /** returns the primal heuristic of the given name, or NULL if not existing */ 172 SCIP_EXPORT 173 SCIP_HEUR* SCIPfindHeur( 174 SCIP* scip, /**< SCIP data structure */ 175 const char* name /**< name of primal heuristic */ 176 ); 177 178 /** returns the array of currently available primal heuristics */ 179 SCIP_EXPORT 180 SCIP_HEUR** SCIPgetHeurs( 181 SCIP* scip /**< SCIP data structure */ 182 ); 183 184 /** returns the number of currently available primal heuristics */ 185 SCIP_EXPORT 186 int SCIPgetNHeurs( 187 SCIP* scip /**< SCIP data structure */ 188 ); 189 190 /** sets the priority of a primal heuristic */ 191 SCIP_EXPORT 192 SCIP_RETCODE SCIPsetHeurPriority( 193 SCIP* scip, /**< SCIP data structure */ 194 SCIP_HEUR* heur, /**< primal heuristic */ 195 int priority /**< new priority of the primal heuristic */ 196 ); 197 198 /** @} */ 199 200 /**@addtogroup PublicDivesetMethods 201 * 202 * @{ 203 */ 204 205 /** create a diving set associated with a primal heuristic. The primal heuristic needs to be included 206 * before this method can be called. The diveset is installed in the array of divesets of the heuristic 207 * and can be retrieved later by accessing SCIPheurGetDivesets() 208 * 209 * @return \ref SCIP_OKAY is returned if everything worked. otherwise a suitable error code is passed. see \ref 210 * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes. 211 * 212 * @pre This method can be called if @p scip is in one of the following stages: 213 * - \ref SCIP_STAGE_INIT 214 * - \ref SCIP_STAGE_PROBLEM 215 */ 216 SCIP_EXPORT 217 SCIP_RETCODE SCIPcreateDiveset( 218 SCIP* scip, /**< SCIP data structure */ 219 SCIP_DIVESET** diveset, /**< pointer to created diving heuristic settings, or NULL if not needed */ 220 SCIP_HEUR* heur, /**< primal heuristic to which the diveset belongs */ 221 const char* name, /**< name for the diveset, or NULL if the name of the heuristic should be used */ 222 SCIP_Real minreldepth, /**< minimal relative depth to start diving */ 223 SCIP_Real maxreldepth, /**< maximal relative depth to start diving */ 224 SCIP_Real maxlpiterquot, /**< maximal fraction of diving LP iterations compared to node LP iterations */ 225 SCIP_Real maxdiveubquot, /**< maximal quotient (curlowerbound - lowerbound)/(cutoffbound - lowerbound) 226 * where diving is performed (0.0: no limit) */ 227 SCIP_Real maxdiveavgquot, /**< maximal quotient (curlowerbound - lowerbound)/(avglowerbound - lowerbound) 228 * where diving is performed (0.0: no limit) */ 229 SCIP_Real maxdiveubquotnosol, /**< maximal UBQUOT when no solution was found yet (0.0: no limit) */ 230 SCIP_Real maxdiveavgquotnosol,/**< maximal AVGQUOT when no solution was found yet (0.0: no limit) */ 231 SCIP_Real lpresolvedomchgquot,/**< percentage of immediate domain changes during probing to trigger LP resolve */ 232 int lpsolvefreq, /**< LP solve frequency for (0: only if enough domain reductions are found by propagation)*/ 233 int maxlpiterofs, /**< additional number of allowed LP iterations */ 234 unsigned int initialseed, /**< initial seed for random number generation */ 235 SCIP_Bool backtrack, /**< use one level of backtracking if infeasibility is encountered? */ 236 SCIP_Bool onlylpbranchcands, /**< should only LP branching candidates be considered instead of the slower but 237 * more general constraint handler diving variable selection? */ 238 SCIP_Bool ispublic, /**< is this dive set publicly available (ie., can be used by other primal heuristics?) */ 239 SCIP_Bool specificsos1score, /**< should SOS1 variables be scored by the diving heuristics specific score function; 240 * otherwise use the score function of the SOS1 constraint handler */ 241 SCIP_DECL_DIVESETGETSCORE((*divesetgetscore)), /**< method for candidate score and rounding direction */ 242 SCIP_DECL_DIVESETAVAILABLE((*divesetavailable)) /**< callback to check availability of dive set at the current stage, or NULL if always available */ 243 ); 244 245 /** check specific preconditions for diving, e.g., if an incumbent solution is available */ 246 SCIP_EXPORT 247 SCIP_RETCODE SCIPisDivesetAvailable( 248 SCIP* scip, /**< SCIP data structure */ 249 SCIP_DIVESET* diveset, /**< diving heuristic settings */ 250 SCIP_Bool* available /**< pointer to store if the diving can run at the current solving stage */ 251 ); 252 253 /** @} */ 254 255 #ifdef __cplusplus 256 } 257 #endif 258 259 #endif 260