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