Scippy

SCIP

Solving Constraint Integer Programs

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-2022 Konrad-Zuse-Zentrum */
7 /* fuer Informationstechnik Berlin */
8 /* */
9 /* SCIP is distributed under the terms of the ZIB Academic License. */
10 /* */
11 /* You should have received a copy of the ZIB Academic License */
12 /* along with SCIP; see the file COPYING. If not visit scipopt.org. */
13 /* */
14 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
15 
16 /**@file heur.h
17  * @ingroup INTERNALAPI
18  * @brief internal methods for primal heuristics
19  * @author Tobias Achterberg
20  */
21 
22 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
23 
24 #ifndef __SCIP_HEUR_H__
25 #define __SCIP_HEUR_H__
26 
27 
28 #include "scip/def.h"
29 #include "blockmemshell/memory.h"
30 #include "scip/type_retcode.h"
31 #include "scip/type_result.h"
32 #include "scip/type_set.h"
33 #include "scip/type_primal.h"
34 #include "scip/type_heur.h"
35 #include "scip/pub_heur.h"
36 #include "scip/stat.h"
37 
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41 
42 /** create a set of diving heuristic settings */
44  SCIP_DIVESET** divesetptr, /**< pointer to the freshly created diveset */
45  SCIP_HEUR* heur, /**< the heuristic to which this dive setting belongs */
46  const char* name, /**< name for the diveset, or NULL if the name of the heuristic should be used */
47  SCIP_SET* set, /**< global SCIP settings */
48  SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */
49  BMS_BLKMEM* blkmem, /**< block memory for parameter settings */
50  SCIP_Real minreldepth, /**< minimal relative depth to start diving */
51  SCIP_Real maxreldepth, /**< maximal relative depth to start diving */
52  SCIP_Real maxlpiterquot, /**< maximal fraction of diving LP iterations compared to node LP iterations */
53  SCIP_Real maxdiveubquot, /**< maximal quotient (curlowerbound - lowerbound)/(cutoffbound - lowerbound)
54  * where diving is performed (0.0: no limit) */
55  SCIP_Real maxdiveavgquot, /**< maximal quotient (curlowerbound - lowerbound)/(avglowerbound - lowerbound)
56  * where diving is performed (0.0: no limit) */
57  SCIP_Real maxdiveubquotnosol, /**< maximal UBQUOT when no solution was found yet (0.0: no limit) */
58  SCIP_Real maxdiveavgquotnosol,/**< maximal AVGQUOT when no solution was found yet (0.0: no limit) */
59  SCIP_Real lpresolvedomchgquot,/**< percentage of immediate domain changes during probing to trigger LP resolve */
60  int lpsolvefreq, /**< LP solve frequency for (0: only if enough domain reductions are found by propagation)*/
61  int maxlpiterofs, /**< additional number of allowed LP iterations */
62  unsigned int initialseed, /**< initial seed for random number generation */
63  SCIP_Bool backtrack, /**< use one level of backtracking if infeasibility is encountered? */
64  SCIP_Bool onlylpbranchcands, /**< should only LP branching candidates be considered instead of the slower but
65  * more general constraint handler diving variable selection? */
66  SCIP_Bool ispublic, /**< is this dive set publicly available (ie., can be used by other primal heuristics?) */
67  SCIP_DIVETYPE divetypemask, /**< bit mask that represents the supported dive types by this dive set */
68  SCIP_DECL_DIVESETGETSCORE((*divesetgetscore)), /**< method for candidate score and rounding direction */
69  SCIP_DECL_DIVESETAVAILABLE((*divesetavailable)) /**< callback to check availability of dive set at the current stage, or NULL if always available */
70  );
71 
72 /** resets diving settings counters */
74  SCIP_DIVESET* diveset, /**< diveset to be reset */
75  SCIP_SET* set /**< global SCIP settings */
76  );
77 
78 /** update diveset statistics and global diveset statistics */
80  SCIP_DIVESET* diveset, /**< diveset to be reset */
81  SCIP_STAT* stat, /**< global SCIP statistics */
82  int depth, /**< the depth reached this time */
83  int nprobingnodes, /**< the number of probing nodes explored this time */
84  int nbacktracks, /**< the number of backtracks during probing this time */
85  SCIP_Longint nsolsfound, /**< number of new solutions found this time */
86  SCIP_Longint nbestsolsfound, /**< number of new best solutions found this time */
87  SCIP_Longint nconflictsfound, /**< number of new conflicts found this time */
88  SCIP_Bool leavesol, /**< has the diving heuristic reached a feasible leaf */
89  SCIP_DIVECONTEXT divecontext /**< context for diving statistics */
90  );
91 
92 /** get the candidate score and preferred rounding direction for a candidate variable */
94  SCIP_DIVESET* diveset, /**< general diving settings */
95  SCIP_SET* set, /**< SCIP settings */
96  SCIP_DIVETYPE divetype, /**< the type of diving that should be applied */
97  SCIP_VAR* divecand, /**< the candidate for which the branching direction is requested */
98  SCIP_Real divecandsol, /**< LP solution value of the candidate */
99  SCIP_Real divecandfrac, /**< fractionality of the candidate */
100  SCIP_Real* candscore, /**< pointer to store the candidate score */
101  SCIP_Bool* roundup /**< pointer to store whether preferred direction for diving is upwards */
102  );
103 
104 /** check specific preconditions for diving, e.g., if an incumbent solution is available */
106  SCIP_DIVESET* diveset, /**< diving heuristic settings */
107  SCIP_SET* set, /**< SCIP settings */
108  SCIP_Bool* available /**< pointer to store if the diving can run at the current solving stage */
109  );
110 
111 /** update diveset LP statistics, should be called after every LP solved by this diving heuristic */
113  SCIP_DIVESET* diveset, /**< diving settings */
114  SCIP_STAT* stat, /**< global SCIP statistics */
115  SCIP_Longint niterstoadd, /**< additional number of LP iterations to be added */
116  SCIP_DIVECONTEXT divecontext /**< context for diving statistics */
117  );
118 
119 /** copies the given primal heuristic to a new scip */
121  SCIP_HEUR* heur, /**< primal heuristic */
122  SCIP_SET* set /**< SCIP_SET of SCIP to copy to */
123  );
124 
125 /** creates a primal heuristic */
127  SCIP_HEUR** heur, /**< pointer to primal heuristic data structure */
128  SCIP_SET* set, /**< global SCIP settings */
129  SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */
130  BMS_BLKMEM* blkmem, /**< block memory for parameter settings */
131  const char* name, /**< name of primal heuristic */
132  const char* desc, /**< description of primal heuristic */
133  char dispchar, /**< display character of primal heuristic */
134  int priority, /**< priority of the primal heuristic */
135  int freq, /**< frequency for calling primal heuristic */
136  int freqofs, /**< frequency offset for calling primal heuristic */
137  int maxdepth, /**< maximal depth level to call heuristic at (-1: no limit) */
138  SCIP_HEURTIMING timingmask, /**< positions in the node solving loop where heuristic should be executed */
139  SCIP_Bool usessubscip, /**< does the heuristic use a secondary SCIP instance? */
140  SCIP_DECL_HEURCOPY ((*heurcopy)), /**< copy method of primal heuristic or NULL if you don't want to copy your plugin into sub-SCIPs */
141  SCIP_DECL_HEURFREE ((*heurfree)), /**< destructor of primal heuristic */
142  SCIP_DECL_HEURINIT ((*heurinit)), /**< initialize primal heuristic */
143  SCIP_DECL_HEUREXIT ((*heurexit)), /**< deinitialize primal heuristic */
144  SCIP_DECL_HEURINITSOL ((*heurinitsol)), /**< solving process initialization method of primal heuristic */
145  SCIP_DECL_HEUREXITSOL ((*heurexitsol)), /**< solving process deinitialization method of primal heuristic */
146  SCIP_DECL_HEUREXEC ((*heurexec)), /**< execution method of primal heuristic */
147  SCIP_HEURDATA* heurdata /**< primal heuristic data */
148  );
149 
150 /** calls destructor and frees memory of primal heuristic */
152  SCIP_HEUR** heur, /**< pointer to primal heuristic data structure */
153  SCIP_SET* set, /**< global SCIP settings */
154  BMS_BLKMEM* blkmem /**< block memory */
155  );
156 
157 /** initializes primal heuristic */
159  SCIP_HEUR* heur, /**< primal heuristic */
160  SCIP_SET* set /**< global SCIP settings */
161  );
162 
163 /** calls exit method of primal heuristic */
165  SCIP_HEUR* heur, /**< primal heuristic */
166  SCIP_SET* set /**< global SCIP settings */
167  );
168 
169 /** informs primal heuristic that the branch and bound process is being started */
171  SCIP_HEUR* heur, /**< primal heuristic */
172  SCIP_SET* set /**< global SCIP settings */
173  );
174 
175 /** informs primal heuristic that the branch and bound process data is being freed */
177  SCIP_HEUR* heur, /**< primal heuristic */
178  SCIP_SET* set /**< global SCIP settings */
179  );
180 
181 /** should the heuristic be executed at the given depth, frequency, timing, ... */
183  SCIP_HEUR* heur, /**< primal heuristic */
184  int depth, /**< depth of current node */
185  int lpstateforkdepth, /**< depth of the last node with solved LP */
186  SCIP_HEURTIMING heurtiming, /**< current point in the node solving process */
187  SCIP_Bool* delayed /**< pointer to store whether the heuristic should be delayed */
188  );
189 
190 /** calls execution method of primal heuristic */
192  SCIP_HEUR* heur, /**< primal heuristic */
193  SCIP_SET* set, /**< global SCIP settings */
194  SCIP_PRIMAL* primal, /**< primal data */
195  int depth, /**< depth of current node */
196  int lpstateforkdepth, /**< depth of the last node with solved LP */
197  SCIP_HEURTIMING heurtiming, /**< current point in the node solving process */
198  SCIP_Bool nodeinfeasible, /**< was the current node already detected to be infeasible? */
199  int* ndelayedheurs, /**< pointer to count the number of delayed heuristics */
200  SCIP_RESULT* result /**< pointer to store the result of the callback method */
201  );
202 
203 /** sets priority of primal heuristic */
205  SCIP_HEUR* heur, /**< primal heuristic */
206  SCIP_SET* set, /**< global SCIP settings */
207  int priority /**< new priority of the primal heuristic */
208  );
209 
210 /** sets copy callback of primal heuristic */
211 void SCIPheurSetCopy(
212  SCIP_HEUR* heur, /**< primal heuristic */
213  SCIP_DECL_HEURCOPY ((*heurcopy)) /**< copy callback of primal heuristic or NULL if you don't want to copy your plugin into sub-SCIPs */
214  );
215 
216 /** sets destructor callback of primal heuristic */
217 void SCIPheurSetFree(
218  SCIP_HEUR* heur, /**< primal heuristic */
219  SCIP_DECL_HEURFREE ((*heurfree)) /**< destructor of primal heuristic */
220  );
221 
222 /** sets initialization callback of primal heuristic */
223 void SCIPheurSetInit(
224  SCIP_HEUR* heur, /**< primal heuristic */
225  SCIP_DECL_HEURINIT ((*heurinit)) /**< initialize primal heuristic */
226  );
227 
228 /** sets deinitialization callback of primal heuristic */
229 void SCIPheurSetExit(
230  SCIP_HEUR* heur, /**< primal heuristic */
231  SCIP_DECL_HEUREXIT ((*heurexit)) /**< deinitialize primal heuristic */
232  );
233 
234 /** sets solving process initialization callback of primal heuristic */
235 void SCIPheurSetInitsol(
236  SCIP_HEUR* heur, /**< primal heuristic */
237  SCIP_DECL_HEURINITSOL ((*heurinitsol)) /**< solving process initialization callback of primal heuristic */
238  );
239 
240 /** sets solving process deinitialization callback of primal heuristic */
241 void SCIPheurSetExitsol(
242  SCIP_HEUR* heur, /**< primal heuristic */
243  SCIP_DECL_HEUREXITSOL ((*heurexitsol)) /**< solving process deinitialization callback of primal heuristic */
244  );
245 
246 /** enables or disables all clocks of \p heur, depending on the value of the flag */
248  SCIP_HEUR* heur, /**< the heuristic for which all clocks should be enabled or disabled */
249  SCIP_Bool enable /**< should the clocks of the heuristic be enabled? */
250  );
251 
252 #ifdef __cplusplus
253 }
254 #endif
255 
256 #endif
enum SCIP_Result SCIP_RESULT
Definition: type_result.h:52
#define SCIP_DECL_HEURINITSOL(x)
Definition: type_heur.h:122
SCIP_RETCODE SCIPdivesetGetScore(SCIP_DIVESET *diveset, SCIP_SET *set, SCIP_DIVETYPE divetype, SCIP_VAR *divecand, SCIP_Real divecandsol, SCIP_Real divecandfrac, SCIP_Real *candscore, SCIP_Bool *roundup)
Definition: heur.c:822
void SCIPdivesetUpdateStats(SCIP_DIVESET *diveset, SCIP_STAT *stat, int depth, int nprobingnodes, int nbacktracks, SCIP_Longint nsolsfound, SCIP_Longint nbestsolsfound, SCIP_Longint nconflictsfound, SCIP_Bool leavesol, SCIP_DIVECONTEXT divecontext)
Definition: heur.c:193
SCIP_RETCODE SCIPheurFree(SCIP_HEUR **heur, SCIP_SET *set, BMS_BLKMEM *blkmem)
Definition: heur.c:1016
unsigned int SCIP_HEURTIMING
Definition: type_timing.h:97
void SCIPheurSetExitsol(SCIP_HEUR *heur, SCIP_DECL_HEUREXITSOL((*heurexitsol)))
Definition: heur.c:1430
SCIP_RETCODE SCIPheurExec(SCIP_HEUR *heur, SCIP_SET *set, SCIP_PRIMAL *primal, int depth, int lpstateforkdepth, SCIP_HEURTIMING heurtiming, SCIP_Bool nodeinfeasible, int *ndelayedheurs, SCIP_RESULT *result)
Definition: heur.c:1251
SCIP_RETCODE SCIPheurInitsol(SCIP_HEUR *heur, SCIP_SET *set)
Definition: heur.c:1135
void SCIPheurSetPriority(SCIP_HEUR *heur, SCIP_SET *set, int priority)
Definition: heur.c:1512
#define SCIP_DECL_HEURCOPY(x)
Definition: type_heur.h:87
enum SCIP_Retcode SCIP_RETCODE
Definition: type_retcode.h:54
#define SCIP_DECL_HEUREXEC(x)
Definition: type_heur.h:153
type definitions for global SCIP settings
struct SCIP_HeurData SCIP_HEURDATA
Definition: type_heur.h:67
SCIP_RETCODE SCIPdivesetReset(SCIP_DIVESET *diveset, SCIP_SET *set)
Definition: heur.c:121
SCIP_RETCODE SCIPheurCreate(SCIP_HEUR **heur, SCIP_SET *set, SCIP_MESSAGEHDLR *messagehdlr, BMS_BLKMEM *blkmem, 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: heur.c:977
type definitions for return codes for SCIP methods
unsigned int SCIP_DIVETYPE
Definition: type_heur.h:54
#define SCIP_DECL_DIVESETGETSCORE(x)
Definition: type_heur.h:174
SCIP_RETCODE SCIPheurCopyInclude(SCIP_HEUR *heur, SCIP_SET *set)
Definition: heur.c:870
type definitions for primal heuristics
SCIP_Bool SCIPheurShouldBeExecuted(SCIP_HEUR *heur, int depth, int lpstateforkdepth, SCIP_HEURTIMING heurtiming, SCIP_Bool *delayed)
Definition: heur.c:1189
void SCIPheurSetCopy(SCIP_HEUR *heur, SCIP_DECL_HEURCOPY((*heurcopy)))
Definition: heur.c:1375
void SCIPheurSetFree(SCIP_HEUR *heur, SCIP_DECL_HEURFREE((*heurfree)))
Definition: heur.c:1386
#define SCIP_Bool
Definition: def.h:84
SCIP_RETCODE SCIPheurInit(SCIP_HEUR *heur, SCIP_SET *set)
Definition: heur.c:1052
SCIP_RETCODE SCIPdivesetIsAvailable(SCIP_DIVESET *diveset, SCIP_SET *set, SCIP_Bool *available)
Definition: heur.c:846
#define SCIP_DECL_DIVESETAVAILABLE(x)
Definition: type_heur.h:189
void SCIPheurEnableOrDisableClocks(SCIP_HEUR *heur, SCIP_Bool enable)
Definition: heur.c:1607
enum SCIP_DiveContext SCIP_DIVECONTEXT
Definition: type_heur.h:63
SCIP_RETCODE SCIPheurExit(SCIP_HEUR *heur, SCIP_SET *set)
Definition: heur.c:1105
#define SCIP_DECL_HEUREXIT(x)
Definition: type_heur.h:111
#define SCIP_DECL_HEURINIT(x)
Definition: type_heur.h:103
#define SCIP_Real
Definition: def.h:177
internal methods for problem statistics
result codes for SCIP callback methods
#define SCIP_DECL_HEURFREE(x)
Definition: type_heur.h:95
void SCIPdivesetUpdateLPStats(SCIP_DIVESET *diveset, SCIP_STAT *stat, SCIP_Longint niterstoadd, SCIP_DIVECONTEXT divecontext)
Definition: heur.c:776
SCIP_RETCODE SCIPheurExitsol(SCIP_HEUR *heur, SCIP_SET *set)
Definition: heur.c:1165
#define SCIP_Longint
Definition: def.h:162
void SCIPheurSetExit(SCIP_HEUR *heur, SCIP_DECL_HEUREXIT((*heurexit)))
Definition: heur.c:1408
void SCIPheurSetInit(SCIP_HEUR *heur, SCIP_DECL_HEURINIT((*heurinit)))
Definition: heur.c:1397
type definitions for collecting primal CIP solutions and primal informations
public methods for primal heuristics
common defines and data types used in all packages of SCIP
struct BMS_BlkMem BMS_BLKMEM
Definition: memory.h:430
SCIP_RETCODE SCIPdivesetCreate(SCIP_DIVESET **divesetptr, SCIP_HEUR *heur, const char *name, SCIP_SET *set, SCIP_MESSAGEHDLR *messagehdlr, BMS_BLKMEM *blkmem, 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_DIVETYPE divetypemask, SCIP_DECL_DIVESETGETSCORE((*divesetgetscore)), SCIP_DECL_DIVESETAVAILABLE((*divesetavailable)))
Definition: heur.c:255
#define SCIP_DECL_HEUREXITSOL(x)
Definition: type_heur.h:133
void SCIPheurSetInitsol(SCIP_HEUR *heur, SCIP_DECL_HEURINITSOL((*heurinitsol)))
Definition: heur.c:1419
memory allocation routines