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-2019 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 scip.zib.de. */
13 /* */
14 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
15 
16 /**@file scip_heur.h
17  * @ingroup PUBLICCOREAPI
18  * @brief public methods for primal heuristic plugins and divesets
19  * @author Tobias Achterberg
20  * @author Timo Berthold
21  * @author Thorsten Koch
22  * @author Alexander Martin
23  * @author Marc Pfetsch
24  * @author Kati Wolter
25  * @author Gregor Hendel
26  * @author Robert Lion Gottwald
27  */
28 
29 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
30 
31 #ifndef __SCIP_SCIP_HEUR_H__
32 #define __SCIP_SCIP_HEUR_H__
33 
34 
35 #include "scip/def.h"
36 #include "scip/type_heur.h"
37 #include "scip/type_result.h"
38 #include "scip/type_retcode.h"
39 #include "scip/type_scip.h"
40 #include "scip/type_timing.h"
41 #include "scip/type_var.h"
42 
43 /* In debug mode, we include the SCIP's structure in scip.c, such that no one can access
44  * this structure except the interface methods in scip.c.
45  * In optimized mode, the structure is included in scip.h, because some of the methods
46  * are implemented as defines for performance reasons (e.g. the numerical comparisons).
47  * Additionally, the internal "set.h" is included, such that the defines in set.h are
48  * available in optimized mode.
49  */
50 #ifdef NDEBUG
51 #include "scip/struct_scip.h"
52 #include "scip/struct_stat.h"
53 #include "scip/set.h"
54 #include "scip/tree.h"
55 #include "scip/misc.h"
56 #include "scip/var.h"
57 #include "scip/cons.h"
58 #include "scip/solve.h"
59 #include "scip/debug.h"
60 #endif
61 
62 #ifdef __cplusplus
63 extern "C" {
64 #endif
65 
66 /**@addtogroup PublicHeuristicMethods
67  *
68  * @{
69  */
70 
71 /** creates a primal heuristic and includes it in SCIP.
72  *
73  * @note method has all heuristic callbacks as arguments and is thus changed every time a new
74  * callback is added in future releases; consider using SCIPincludeHeurBasic() and setter functions
75  * if you seek for a method which is less likely to change in future releases
76  *
77  * @return \ref SCIP_OKAY is returned if everything worked. otherwise a suitable error code is passed. see \ref
78  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
79  *
80  * @pre This method can be called if @p scip is in one of the following stages:
81  * - \ref SCIP_STAGE_INIT
82  * - \ref SCIP_STAGE_PROBLEM
83  */
84 extern
86  SCIP* scip, /**< SCIP data structure */
87  const char* name, /**< name of primal heuristic */
88  const char* desc, /**< description of primal heuristic */
89  char dispchar, /**< display character of primal heuristic */
90  int priority, /**< priority of the primal heuristic */
91  int freq, /**< frequency for calling primal heuristic */
92  int freqofs, /**< frequency offset for calling primal heuristic */
93  int maxdepth, /**< maximal depth level to call heuristic at (-1: no limit) */
94  SCIP_HEURTIMING timingmask, /**< positions in the node solving loop where heuristic should be executed;
95  * see definition of SCIP_HEURTIMING for possible values */
96  SCIP_Bool usessubscip, /**< does the heuristic use a secondary SCIP instance? */
97  SCIP_DECL_HEURCOPY ((*heurcopy)), /**< copy method of primal heuristic or NULL if you don't want to copy your plugin into sub-SCIPs */
98  SCIP_DECL_HEURFREE ((*heurfree)), /**< destructor of primal heuristic */
99  SCIP_DECL_HEURINIT ((*heurinit)), /**< initialize primal heuristic */
100  SCIP_DECL_HEUREXIT ((*heurexit)), /**< deinitialize primal heuristic */
101  SCIP_DECL_HEURINITSOL ((*heurinitsol)), /**< solving process initialization method of primal heuristic */
102  SCIP_DECL_HEUREXITSOL ((*heurexitsol)), /**< solving process deinitialization method of primal heuristic */
103  SCIP_DECL_HEUREXEC ((*heurexec)), /**< execution method of primal heuristic */
104  SCIP_HEURDATA* heurdata /**< primal heuristic data */
105  );
106 
107 /** creates a primal heuristic and includes it in SCIP with its most fundamental callbacks.
108  * All non-fundamental (or optional) callbacks
109  * as, e. g., init and exit callbacks, will be set to NULL.
110  * Optional callbacks can be set via specific setter functions, see SCIPsetHeurCopy(), SCIPsetHeurFree(),
111  * SCIPsetHeurInit(), SCIPsetHeurExit(), SCIPsetHeurInitsol(), and SCIPsetHeurExitsol()
112  *
113 * @note if you want to set all callbacks with a single method call, consider using SCIPincludeHeur() instead
114  */
115 extern
117  SCIP* scip, /**< SCIP data structure */
118  SCIP_HEUR** heur, /**< pointer to the heuristic */
119  const char* name, /**< name of primal heuristic */
120  const char* desc, /**< description of primal heuristic */
121  char dispchar, /**< display character of primal heuristic */
122  int priority, /**< priority of the primal heuristic */
123  int freq, /**< frequency for calling primal heuristic */
124  int freqofs, /**< frequency offset for calling primal heuristic */
125  int maxdepth, /**< maximal depth level to call heuristic at (-1: no limit) */
126  SCIP_HEURTIMING timingmask, /**< positions in the node solving loop where heuristic should be executed;
127  * see definition of SCIP_HEURTIMING for possible values */
128  SCIP_Bool usessubscip, /**< does the heuristic use a secondary SCIP instance? */
129  SCIP_DECL_HEUREXEC ((*heurexec)), /**< execution method of primal heuristic */
130  SCIP_HEURDATA* heurdata /**< primal heuristic data */
131  );
132 
133 /** sets copy method of primal heuristic */
134 extern
136  SCIP* scip, /**< SCIP data structure */
137  SCIP_HEUR* heur, /**< primal heuristic */
138  SCIP_DECL_HEURCOPY ((*heurcopy)) /**< copy method of primal heuristic or NULL if you don't want to copy your plugin into sub-SCIPs */
139  );
140 
141 /** sets destructor method of primal heuristic */
142 extern
144  SCIP* scip, /**< SCIP data structure */
145  SCIP_HEUR* heur, /**< primal heuristic */
146  SCIP_DECL_HEURFREE ((*heurfree)) /**< destructor of primal heuristic */
147  );
148 
149 /** sets initialization method of primal heuristic */
150 extern
152  SCIP* scip, /**< SCIP data structure */
153  SCIP_HEUR* heur, /**< primal heuristic */
154  SCIP_DECL_HEURINIT ((*heurinit)) /**< initialize primal heuristic */
155  );
156 
157 /** sets deinitialization method of primal heuristic */
158 extern
160  SCIP* scip, /**< SCIP data structure */
161  SCIP_HEUR* heur, /**< primal heuristic */
162  SCIP_DECL_HEUREXIT ((*heurexit)) /**< deinitialize primal heuristic */
163  );
164 
165 /** sets solving process initialization method of primal heuristic */
166 extern
168  SCIP* scip, /**< SCIP data structure */
169  SCIP_HEUR* heur, /**< primal heuristic */
170  SCIP_DECL_HEURINITSOL ((*heurinitsol)) /**< solving process initialization method of primal heuristic */
171  );
172 
173 /** sets solving process deinitialization method of primal heuristic */
174 extern
176  SCIP* scip, /**< SCIP data structure */
177  SCIP_HEUR* heur, /**< primal heuristic */
178  SCIP_DECL_HEUREXITSOL ((*heurexitsol)) /**< solving process deinitialization method of primal heuristic */
179  );
180 
181 /** returns the primal heuristic of the given name, or NULL if not existing */
182 extern
184  SCIP* scip, /**< SCIP data structure */
185  const char* name /**< name of primal heuristic */
186  );
187 
188 /** returns the array of currently available primal heuristics */
189 extern
191  SCIP* scip /**< SCIP data structure */
192  );
193 
194 /** returns the number of currently available primal heuristics */
195 extern
196 int SCIPgetNHeurs(
197  SCIP* scip /**< SCIP data structure */
198  );
199 
200 /** sets the priority of a primal heuristic */
201 extern
203  SCIP* scip, /**< SCIP data structure */
204  SCIP_HEUR* heur, /**< primal heuristic */
205  int priority /**< new priority of the primal heuristic */
206  );
207 
208 /* @} */
209 
210 /**@addtogroup PublicDivesetMethods
211  *
212  * @{
213  */
214 
215 /** create a diving set associated with a primal heuristic. The primal heuristic needs to be included
216  * before this method can be called. The diveset is installed in the array of divesets of the heuristic
217  * and can be retrieved later by accessing SCIPheurGetDivesets()
218  *
219  * @return \ref SCIP_OKAY is returned if everything worked. otherwise a suitable error code is passed. see \ref
220  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
221  *
222  * @pre This method can be called if @p scip is in one of the following stages:
223  * - \ref SCIP_STAGE_INIT
224  * - \ref SCIP_STAGE_PROBLEM
225  */
226 extern
228  SCIP* scip, /**< SCIP data structure */
229  SCIP_DIVESET** diveset, /**< pointer to created diving heuristic settings, or NULL if not needed */
230  SCIP_HEUR* heur, /**< primal heuristic to which the diveset belongs */
231  const char* name, /**< name for the diveset, or NULL if the name of the heuristic should be used */
232  SCIP_Real minreldepth, /**< minimal relative depth to start diving */
233  SCIP_Real maxreldepth, /**< maximal relative depth to start diving */
234  SCIP_Real maxlpiterquot, /**< maximal fraction of diving LP iterations compared to node LP iterations */
235  SCIP_Real maxdiveubquot, /**< maximal quotient (curlowerbound - lowerbound)/(cutoffbound - lowerbound)
236  * where diving is performed (0.0: no limit) */
237  SCIP_Real maxdiveavgquot, /**< maximal quotient (curlowerbound - lowerbound)/(avglowerbound - lowerbound)
238  * where diving is performed (0.0: no limit) */
239  SCIP_Real maxdiveubquotnosol, /**< maximal UBQUOT when no solution was found yet (0.0: no limit) */
240  SCIP_Real maxdiveavgquotnosol,/**< maximal AVGQUOT when no solution was found yet (0.0: no limit) */
241  SCIP_Real lpresolvedomchgquot,/**< percentage of immediate domain changes during probing to trigger LP resolve */
242  int lpsolvefreq, /**< LP solve frequency for (0: only if enough domain reductions are found by propagation)*/
243  int maxlpiterofs, /**< additional number of allowed LP iterations */
244  unsigned int initialseed, /**< initial seed for random number generation */
245  SCIP_Bool backtrack, /**< use one level of backtracking if infeasibility is encountered? */
246  SCIP_Bool onlylpbranchcands, /**< should only LP branching candidates be considered instead of the slower but
247  * more general constraint handler diving variable selection? */
248  SCIP_Bool specificsos1score, /**< should SOS1 variables be scored by the diving heuristics specific score function;
249  * otherwise use the score function of the SOS1 constraint handler */
250  SCIP_DECL_DIVESETGETSCORE((*divesetgetscore)) /**< method for candidate score and rounding direction */
251 
252  );
253 
254 /* @} */
255 
256 #ifdef __cplusplus
257 }
258 #endif
259 
260 #endif
SCIP_RETCODE SCIPsetHeurExitsol(SCIP *scip, SCIP_HEUR *heur, SCIP_DECL_HEUREXITSOL((*heurexitsol)))
Definition: scip_heur.c:312
#define SCIP_DECL_HEURINITSOL(x)
Definition: type_heur.h:97
internal methods for branch and bound tree
timing definitions for SCIP
unsigned int SCIP_HEURTIMING
Definition: type_timing.h:97
SCIP_RETCODE SCIPsetHeurExit(SCIP *scip, SCIP_HEUR *heur, SCIP_DECL_HEUREXIT((*heurexit)))
Definition: scip_heur.c:280
#define SCIP_DECL_HEURCOPY(x)
Definition: type_heur.h:62
enum SCIP_Retcode SCIP_RETCODE
Definition: type_retcode.h:53
#define SCIP_DECL_HEUREXEC(x)
Definition: type_heur.h:128
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:137
SCIP_HEUR ** SCIPgetHeurs(SCIP *scip)
Definition: scip_heur.c:341
struct SCIP_HeurData SCIP_HEURDATA
Definition: type_heur.h:51
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:187
type definitions for return codes for SCIP methods
#define SCIP_DECL_DIVESETGETSCORE(x)
Definition: type_heur.h:149
SCIP_RETCODE SCIPsetHeurPriority(SCIP *scip, SCIP_HEUR *heur, int priority)
Definition: scip_heur.c:365
SCIP_RETCODE SCIPsetHeurInitsol(SCIP *scip, SCIP_HEUR *heur, SCIP_DECL_HEURINITSOL((*heurinitsol)))
Definition: scip_heur.c:296
SCIP_HEUR * SCIPfindHeur(SCIP *scip, const char *name)
Definition: scip_heur.c:328
SCIP_RETCODE SCIPsetHeurFree(SCIP *scip, SCIP_HEUR *heur, SCIP_DECL_HEURFREE((*heurfree)))
Definition: scip_heur.c:248
type definitions for primal heuristics
type definitions for SCIP&#39;s main datastructure
internal miscellaneous methods
internal methods for global SCIP settings
SCIP main data structure.
type definitions for problem variables
internal methods for problem variables
#define SCIP_Bool
Definition: def.h:69
methods for debugging
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 specificsos1score, SCIP_DECL_DIVESETGETSCORE((*divesetgetscore)))
Definition: scip_heur.c:390
datastructures for problem statistics
int SCIPgetNHeurs(SCIP *scip)
Definition: scip_heur.c:354
internal methods for main solving loop and node processing
#define SCIP_DECL_HEUREXIT(x)
Definition: type_heur.h:86
#define SCIP_DECL_HEURINIT(x)
Definition: type_heur.h:78
SCIP_RETCODE SCIPsetHeurInit(SCIP *scip, SCIP_HEUR *heur, SCIP_DECL_HEURINIT((*heurinit)))
Definition: scip_heur.c:264
#define SCIP_Real
Definition: def.h:157
result codes for SCIP callback methods
#define SCIP_DECL_HEURFREE(x)
Definition: type_heur.h:70
internal methods for constraints and constraint handlers
SCIP_RETCODE SCIPsetHeurCopy(SCIP *scip, SCIP_HEUR *heur, SCIP_DECL_HEURCOPY((*heurcopy)))
Definition: scip_heur.c:232
common defines and data types used in all packages of SCIP
#define SCIP_DECL_HEUREXITSOL(x)
Definition: type_heur.h:108