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 objheur.h 26 * @brief C++ wrapper for primal heuristics 27 * @author Tobias Achterberg 28 */ 29 30 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/ 31 32 #ifndef __SCIP_OBJHEUR_H__ 33 #define __SCIP_OBJHEUR_H__ 34 35 #include <cstring> 36 #include <utility> 37 38 #include "scip/scip.h" 39 #include "objscip/objcloneable.h" 40 41 namespace scip 42 { 43 44 /** @brief C++ wrapper for primal heuristics 45 * 46 * This class defines the interface for primal heuristics implemented in C++. Note that there is a pure virtual 47 * function (this function has to be implemented). This function is: scip_exec(). 48 * 49 * - \ref HEUR "Instructions for implementing a primal heuristic" 50 * - \ref PRIMALHEURISTICS "List of available primal heuristics" 51 * - \ref type_heur.h "Corresponding C interface" 52 */ 53 class ObjHeur : public ObjCloneable 54 { 55 public: 56 /*lint --e{1540}*/ 57 58 /** SCIP data structure */ 59 SCIP* scip_; 60 61 /** name of the primal heuristic */ 62 char* scip_name_; 63 64 /** description of the primal heuristic */ 65 char* scip_desc_; 66 67 /** display character of primal heuristic */ 68 const char scip_dispchar_; 69 70 /** default priority of the primal heuristic */ 71 const int scip_priority_; 72 73 /** frequency for calling primal heuristic */ 74 const int scip_freq_; 75 76 /** frequency offset for calling primal heuristic */ 77 const int scip_freqofs_; 78 79 /** maximal depth level to call heuristic at (-1: no limit) */ 80 const int scip_maxdepth_; 81 82 /** positions in the node solving loop where heuristic should be executed */ 83 const SCIP_HEURTIMING scip_timingmask_; 84 85 /** does the heuristic use a secondary SCIP instance? */ 86 const SCIP_Bool scip_usessubscip_; 87 88 /** default constructor */ 89 ObjHeur( 90 SCIP* scip, /**< SCIP data structure */ 91 const char* name, /**< name of primal heuristic */ 92 const char* desc, /**< description of primal heuristic */ 93 char dispchar, /**< display character of primal heuristic */ 94 int priority, /**< priority of the primal heuristic */ 95 int freq, /**< frequency for calling primal heuristic */ 96 int freqofs, /**< frequency offset for calling primal heuristic */ 97 int maxdepth, /**< maximal depth level to call heuristic at (-1: no limit) */ 98 SCIP_HEURTIMING timingmask, /**< positions in the node solving loop where heuristic should be executed; 99 * see definition of SCIP_HEURTIMING for possible values */ 100 SCIP_Bool usessubscip /**< does the heuristic use a secondary SCIP instance? */ 101 ) 102 : scip_(scip), 103 scip_name_(0), 104 scip_desc_(0), 105 scip_dispchar_(dispchar), 106 scip_priority_(priority), 107 scip_freq_(freq), 108 scip_freqofs_(freqofs), 109 scip_maxdepth_(maxdepth), 110 scip_timingmask_(timingmask), 111 scip_usessubscip_(usessubscip) 112 { 113 /* the macro SCIPduplicateMemoryArray does not need the first argument: */ 114 SCIP_CALL_ABORT( SCIPduplicateMemoryArray(scip_, &scip_name_, name, std::strlen(name)+1) ); 115 SCIP_CALL_ABORT( SCIPduplicateMemoryArray(scip_, &scip_desc_, desc, std::strlen(desc)+1) ); 116 } 117 118 /** copy constructor */ 119 ObjHeur(const ObjHeur& o) 120 : ObjHeur(o.scip_, o.scip_name_, o.scip_desc_, o.scip_dispchar_, o.scip_priority_, o.scip_freq_, o.scip_freqofs_, 121 o.scip_maxdepth_, o.scip_timingmask_, o.scip_usessubscip_) 122 { 123 } 124 125 /** move constructor */ 126 ObjHeur(ObjHeur&& o) 127 : scip_(o.scip_), 128 scip_name_(0), 129 scip_desc_(0), 130 scip_dispchar_(o.scip_dispchar_), 131 scip_priority_(o.scip_priority_), 132 scip_freq_(o.scip_freq_), 133 scip_freqofs_(o.scip_freqofs_), 134 scip_maxdepth_(o.scip_maxdepth_), 135 scip_timingmask_(o.scip_timingmask_), 136 scip_usessubscip_(o.scip_usessubscip_) 137 { 138 std::swap(scip_name_, o.scip_name_); 139 std::swap(scip_desc_, o.scip_desc_); 140 } 141 142 /** destructor */ 143 virtual ~ObjHeur() 144 { 145 /* the macro SCIPfreeMemoryArray does not need the first argument: */ 146 /*lint --e{64}*/ 147 SCIPfreeMemoryArray(scip_, &scip_name_); 148 SCIPfreeMemoryArray(scip_, &scip_desc_); 149 } 150 151 /** assignment of polymorphic classes causes slicing and is therefore disabled. */ 152 ObjHeur& operator=(const ObjHeur& o) = delete; 153 154 /** assignment of polymorphic classes causes slicing and is therefore disabled. */ 155 ObjHeur& operator=(ObjHeur&& o) = delete; 156 157 /** destructor of primal heuristic to free user data (called when SCIP is exiting) 158 * 159 * @see SCIP_DECL_HEURFREE(x) in @ref type_heur.h 160 */ 161 virtual SCIP_DECL_HEURFREE(scip_free) 162 { /*lint --e{715}*/ 163 return SCIP_OKAY; 164 } 165 166 /** initialization method of primal heuristic (called after problem was transformed) 167 * 168 * @see SCIP_DECL_HEURINIT(x) in @ref type_heur.h 169 */ 170 virtual SCIP_DECL_HEURINIT(scip_init) 171 { /*lint --e{715}*/ 172 return SCIP_OKAY; 173 } 174 175 /** deinitialization method of primal heuristic (called before transformed problem is freed) 176 * 177 * @see SCIP_DECL_HEUREXIT(x) in @ref type_heur.h 178 */ 179 virtual SCIP_DECL_HEUREXIT(scip_exit) 180 { /*lint --e{715}*/ 181 return SCIP_OKAY; 182 } 183 184 /** solving process initialization method of primal heuristic (called when branch and bound process is about to begin) 185 * 186 * @see SCIP_DECL_HEURINITSOL(x) in @ref type_heur.h 187 */ 188 virtual SCIP_DECL_HEURINITSOL(scip_initsol) 189 { /*lint --e{715}*/ 190 return SCIP_OKAY; 191 } 192 193 /** solving process deinitialization method of primal heuristic (called before branch and bound process data is freed) 194 * 195 * @see SCIP_DECL_HEUREXITSOL(x) in @ref type_heur.h 196 */ 197 virtual SCIP_DECL_HEUREXITSOL(scip_exitsol) 198 { /*lint --e{715}*/ 199 return SCIP_OKAY; 200 } 201 202 /** execution method of primal heuristic 203 * 204 * @see SCIP_DECL_HEUREXEC(x) in @ref type_heur.h 205 */ 206 virtual SCIP_DECL_HEUREXEC(scip_exec) = 0; 207 }; 208 209 } /* namespace scip */ 210 211 212 213 /** creates the primal heuristic for the given primal heuristic object and includes it in SCIP 214 * 215 * The method should be called in one of the following ways: 216 * 217 * 1. The user is resposible of deleting the object: 218 * SCIP_CALL( SCIPcreate(&scip) ); 219 * ... 220 * MyHeur* myheur = new MyHeur(...); 221 * SCIP_CALL( SCIPincludeObjHeur(scip, &myheur, FALSE) ); 222 * ... 223 * SCIP_CALL( SCIPfree(&scip) ); 224 * delete myheur; // delete heur AFTER SCIPfree() ! 225 * 226 * 2. The object pointer is passed to SCIP and deleted by SCIP in the SCIPfree() call: 227 * SCIP_CALL( SCIPcreate(&scip) ); 228 * ... 229 * SCIP_CALL( SCIPincludeObjHeur(scip, new MyHeur(...), TRUE) ); 230 * ... 231 * SCIP_CALL( SCIPfree(&scip) ); // destructor of MyHeur is called here 232 */ 233 SCIP_EXPORT 234 SCIP_RETCODE SCIPincludeObjHeur( 235 SCIP* scip, /**< SCIP data structure */ 236 scip::ObjHeur* objheur, /**< primal heuristic object */ 237 SCIP_Bool deleteobject /**< should the primal heuristic object be deleted when heuristic is freed? */ 238 ); 239 240 /** returns the heur object of the given name, or 0 if not existing */ 241 SCIP_EXPORT 242 scip::ObjHeur* SCIPfindObjHeur( 243 SCIP* scip, /**< SCIP data structure */ 244 const char* name /**< name of primal heuristic */ 245 ); 246 247 /** returns the heur object for the given primal heuristic */ 248 SCIP_EXPORT 249 scip::ObjHeur* SCIPgetObjHeur( 250 SCIP* scip, /**< SCIP data structure */ 251 SCIP_HEUR* heur /**< primal heuristic */ 252 ); 253 254 #endif 255