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