Scippy

SCIP

Solving Constraint Integer Programs

scip_heur.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-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
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
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
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
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
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
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
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
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
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
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
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
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
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
SCIP_RETCODE SCIPsetHeurExitsol(SCIP *scip, SCIP_HEUR *heur, SCIP_DECL_HEUREXITSOL((*heurexitsol)))
Definition: scip_heur.c:242
#define SCIP_DECL_HEURINITSOL(x)
Definition: type_heur.h:131
timing definitions for SCIP
unsigned int SCIP_HEURTIMING
Definition: type_timing.h:106
SCIP_RETCODE SCIPsetHeurExit(SCIP *scip, SCIP_HEUR *heur, SCIP_DECL_HEUREXIT((*heurexit)))
Definition: scip_heur.c:210
#define SCIP_DECL_HEURCOPY(x)
Definition: type_heur.h:96
enum SCIP_Retcode SCIP_RETCODE
Definition: type_retcode.h:63
#define SCIP_DECL_HEUREXEC(x)
Definition: type_heur.h:162
SCIP_RETCODE SCIPincludeHeur(SCIP *scip, const char *name, const char *desc, char dispchar, int priority, int freq, int freqofs, int maxdepth, SCIP_HEURTIMING timingmask, SCIP_Bool usessubscip, SCIP_DECL_HEURCOPY((*heurcopy)), SCIP_DECL_HEURFREE((*heurfree)), SCIP_DECL_HEURINIT((*heurinit)), SCIP_DECL_HEUREXIT((*heurexit)), SCIP_DECL_HEURINITSOL((*heurinitsol)), SCIP_DECL_HEUREXITSOL((*heurexitsol)), SCIP_DECL_HEUREXEC((*heurexec)), SCIP_HEURDATA *heurdata)
Definition: scip_heur.c:67
SCIP_HEUR ** SCIPgetHeurs(SCIP *scip)
Definition: scip_heur.c:271
struct SCIP_HeurData SCIP_HEURDATA
Definition: type_heur.h:76
SCIP_RETCODE SCIPincludeHeurBasic(SCIP *scip, SCIP_HEUR **heur, const char *name, const char *desc, char dispchar, int priority, int freq, int freqofs, int maxdepth, SCIP_HEURTIMING timingmask, SCIP_Bool usessubscip, SCIP_DECL_HEUREXEC((*heurexec)), SCIP_HEURDATA *heurdata)
Definition: scip_heur.c:117
type definitions for return codes for SCIP methods
SCIP_RETCODE SCIPcreateDiveset(SCIP *scip, SCIP_DIVESET **diveset, SCIP_HEUR *heur, const char *name, SCIP_Real minreldepth, SCIP_Real maxreldepth, SCIP_Real maxlpiterquot, SCIP_Real maxdiveubquot, SCIP_Real maxdiveavgquot, SCIP_Real maxdiveubquotnosol, SCIP_Real maxdiveavgquotnosol, SCIP_Real lpresolvedomchgquot, int lpsolvefreq, int maxlpiterofs, unsigned int initialseed, SCIP_Bool backtrack, SCIP_Bool onlylpbranchcands, SCIP_Bool ispublic, SCIP_Bool specificsos1score, SCIP_DECL_DIVESETGETSCORE((*divesetgetscore)), SCIP_DECL_DIVESETAVAILABLE((*divesetavailable)))
Definition: scip_heur.c:318
#define SCIP_DECL_DIVESETGETSCORE(x)
Definition: type_heur.h:183
SCIP_RETCODE SCIPsetHeurPriority(SCIP *scip, SCIP_HEUR *heur, int priority)
Definition: scip_heur.c:293
SCIP_RETCODE SCIPsetHeurInitsol(SCIP *scip, SCIP_HEUR *heur, SCIP_DECL_HEURINITSOL((*heurinitsol)))
Definition: scip_heur.c:226
SCIP_HEUR * SCIPfindHeur(SCIP *scip, const char *name)
Definition: scip_heur.c:258
SCIP_RETCODE SCIPsetHeurFree(SCIP *scip, SCIP_HEUR *heur, SCIP_DECL_HEURFREE((*heurfree)))
Definition: scip_heur.c:178
type definitions for primal heuristics
type definitions for SCIP&#39;s main datastructure
type definitions for problem variables
#define SCIP_Bool
Definition: def.h:93
SCIP_RETCODE SCIPisDivesetAvailable(SCIP *scip, SCIP_DIVESET *diveset, SCIP_Bool *available)
Definition: scip_heur.c:363
#define SCIP_DECL_DIVESETAVAILABLE(x)
Definition: type_heur.h:198
int SCIPgetNHeurs(SCIP *scip)
Definition: scip_heur.c:282
#define SCIP_DECL_HEUREXIT(x)
Definition: type_heur.h:120
#define SCIP_DECL_HEURINIT(x)
Definition: type_heur.h:112
SCIP_RETCODE SCIPsetHeurInit(SCIP *scip, SCIP_HEUR *heur, SCIP_DECL_HEURINIT((*heurinit)))
Definition: scip_heur.c:194
#define SCIP_Real
Definition: def.h:186
result codes for SCIP callback methods
#define SCIP_DECL_HEURFREE(x)
Definition: type_heur.h:104
SCIP_RETCODE SCIPsetHeurCopy(SCIP *scip, SCIP_HEUR *heur, SCIP_DECL_HEURCOPY((*heurcopy)))
Definition: scip_heur.c:162
common defines and data types used in all packages of SCIP
#define SCIP_DECL_HEUREXITSOL(x)
Definition: type_heur.h:142