Scippy

SCIP

Solving Constraint Integer Programs

scip_event.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_event.h
17  * @ingroup PUBLICCOREAPI
18  * @brief public methods for event handler plugins and event handlers
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_EVENT_H__
32 #define __SCIP_SCIP_EVENT_H__
33 
34 
35 #include "scip/def.h"
36 #include "scip/type_event.h"
37 #include "scip/type_lp.h"
38 #include "scip/type_retcode.h"
39 #include "scip/type_scip.h"
40 #include "scip/type_var.h"
41 
42 /* In debug mode, we include the SCIP's structure in scip.c, such that no one can access
43  * this structure except the interface methods in scip.c.
44  * In optimized mode, the structure is included in scip.h, because some of the methods
45  * are implemented as defines for performance reasons (e.g. the numerical comparisons).
46  * Additionally, the internal "set.h" is included, such that the defines in set.h are
47  * available in optimized mode.
48  */
49 #ifdef NDEBUG
50 #include "scip/struct_scip.h"
51 #include "scip/struct_stat.h"
52 #include "scip/set.h"
53 #include "scip/tree.h"
54 #include "scip/misc.h"
55 #include "scip/var.h"
56 #include "scip/cons.h"
57 #include "scip/solve.h"
58 #include "scip/debug.h"
59 #endif
60 
61 #ifdef __cplusplus
62 extern "C" {
63 #endif
64 
65 /**@addtogroup PublicEventHandlerMethods
66  *
67  * @{
68  */
69 
70 /** creates an event handler and includes it in SCIP
71  *
72  * @note method has all event handler callbacks as arguments and is thus changed every time a new
73  * callback is added in future releases; consider using SCIPincludeEventhdlrBasic() and setter functions
74  * if you seek for a method which is less likely to change in future releases
75  */
76 extern
78  SCIP* scip, /**< SCIP data structure */
79  const char* name, /**< name of event handler */
80  const char* desc, /**< description of event handler */
81  SCIP_DECL_EVENTCOPY ((*eventcopy)), /**< copy method of event handler or NULL if you don't want to copy your plugin into sub-SCIPs */
82  SCIP_DECL_EVENTFREE ((*eventfree)), /**< destructor of event handler */
83  SCIP_DECL_EVENTINIT ((*eventinit)), /**< initialize event handler */
84  SCIP_DECL_EVENTEXIT ((*eventexit)), /**< deinitialize event handler */
85  SCIP_DECL_EVENTINITSOL((*eventinitsol)), /**< solving process initialization method of event handler */
86  SCIP_DECL_EVENTEXITSOL((*eventexitsol)), /**< solving process deinitialization method of event handler */
87  SCIP_DECL_EVENTDELETE ((*eventdelete)), /**< free specific event data */
88  SCIP_DECL_EVENTEXEC ((*eventexec)), /**< execute event handler */
89  SCIP_EVENTHDLRDATA* eventhdlrdata /**< event handler data */
90  );
91 
92 /** creates an event handler and includes it in SCIP with all its non-fundamental callbacks set
93  * to NULL; if needed, non-fundamental callbacks can be set afterwards via setter functions
94  * SCIPsetEventhdlrCopy(), SCIPsetEventhdlrFree(), SCIPsetEventhdlrInit(), SCIPsetEventhdlrExit(),
95  * SCIPsetEventhdlrInitsol(), SCIPsetEventhdlrExitsol(), and SCIPsetEventhdlrDelete()
96  *
97  * @note if you want to set all callbacks with a single method call, consider using SCIPincludeEventhdlr() instead
98  */
99 extern
101  SCIP* scip, /**< SCIP data structure */
102  SCIP_EVENTHDLR** eventhdlrptr, /**< reference to an event handler, or NULL */
103  const char* name, /**< name of event handler */
104  const char* desc, /**< description of event handler */
105  SCIP_DECL_EVENTEXEC ((*eventexec)), /**< execute event handler */
106  SCIP_EVENTHDLRDATA* eventhdlrdata /**< event handler data */
107  );
108 
109 /** sets copy callback of the event handler */
110 extern
112  SCIP* scip, /**< scip instance */
113  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
114  SCIP_DECL_EVENTCOPY ((*eventcopy)) /**< copy callback of the event handler */
115  );
116 
117 /** sets deinitialization callback of the event handler */
118 extern
120  SCIP* scip, /**< scip instance */
121  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
122  SCIP_DECL_EVENTFREE ((*eventfree)) /**< deinitialization callback of the event handler */
123  );
124 
125 /** sets initialization callback of the event handler */
126 extern
128  SCIP* scip, /**< scip instance */
129  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
130  SCIP_DECL_EVENTINIT ((*eventinit)) /**< initialize event handler */
131  );
132 
133 /** sets deinitialization callback of the event handler */
134 extern
136  SCIP* scip, /**< scip instance */
137  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
138  SCIP_DECL_EVENTEXIT ((*eventexit)) /**< deinitialize event handler */
139  );
140 
141 /** sets solving process initialization callback of the event handler */
142 extern
144  SCIP* scip, /**< scip instance */
145  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
146  SCIP_DECL_EVENTINITSOL((*eventinitsol)) /**< solving process initialization callback of event handler */
147  );
148 
149 /** sets solving process deinitialization callback of the event handler */
150 extern
152  SCIP* scip, /**< scip instance */
153  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
154  SCIP_DECL_EVENTEXITSOL((*eventexitsol)) /**< solving process deinitialization callback of event handler */
155  );
156 
157 /** sets callback of the event handler to free specific event data */
158 extern
160  SCIP* scip, /**< scip instance */
161  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
162  SCIP_DECL_EVENTDELETE ((*eventdelete)) /**< free specific event data */
163  );
164 
165 /** returns the event handler of the given name, or NULL if not existing */
166 extern
168  SCIP* scip, /**< SCIP data structure */
169  const char* name /**< name of event handler */
170  );
171 
172 /** returns the array of currently available event handlers */
173 extern
175  SCIP* scip /**< SCIP data structure */
176  );
177 
178 /** returns the number of currently available event handlers */
179 extern
181  SCIP* scip /**< SCIP data structure */
182  );
183 
184 /* @} */
185 
186 /**@addtogroup PublicEventMethods
187  *
188  * @{
189  */
190 
191 /** catches a global (not variable or row dependent) event
192  *
193  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
194  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
195  *
196  * @pre This method can be called if @p scip is in one of the following stages:
197  * - \ref SCIP_STAGE_TRANSFORMING
198  * - \ref SCIP_STAGE_TRANSFORMED
199  * - \ref SCIP_STAGE_INITPRESOLVE
200  * - \ref SCIP_STAGE_PRESOLVING
201  * - \ref SCIP_STAGE_EXITPRESOLVE
202  * - \ref SCIP_STAGE_PRESOLVED
203  * - \ref SCIP_STAGE_INITSOLVE
204  * - \ref SCIP_STAGE_SOLVING
205  * - \ref SCIP_STAGE_SOLVED
206  * - \ref SCIP_STAGE_EXITSOLVE
207  * - \ref SCIP_STAGE_FREETRANS
208  */
209 extern
211  SCIP* scip, /**< SCIP data structure */
212  SCIP_EVENTTYPE eventtype, /**< event type mask to select events to catch */
213  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
214  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
215  int* filterpos /**< pointer to store position of event filter entry, or NULL */
216  );
217 
218 /** drops a global event (stops to track event)
219  *
220  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
221  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
222  *
223  * @pre This method can be called if @p scip is in one of the following stages:
224  * - \ref SCIP_STAGE_TRANSFORMING
225  * - \ref SCIP_STAGE_TRANSFORMED
226  * - \ref SCIP_STAGE_INITPRESOLVE
227  * - \ref SCIP_STAGE_PRESOLVING
228  * - \ref SCIP_STAGE_EXITPRESOLVE
229  * - \ref SCIP_STAGE_PRESOLVED
230  * - \ref SCIP_STAGE_INITSOLVE
231  * - \ref SCIP_STAGE_SOLVING
232  * - \ref SCIP_STAGE_SOLVED
233  * - \ref SCIP_STAGE_EXITSOLVE
234  * - \ref SCIP_STAGE_FREETRANS
235  */
236 extern
238  SCIP* scip, /**< SCIP data structure */
239  SCIP_EVENTTYPE eventtype, /**< event type mask of dropped event */
240  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
241  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
242  int filterpos /**< position of event filter entry returned by SCIPcatchEvent(), or -1 */
243  );
244 
245 /** catches an objective value or domain change event on the given transformed variable
246  *
247  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
248  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
249  *
250  * @pre This method can be called if @p scip is in one of the following stages:
251  * - \ref SCIP_STAGE_TRANSFORMING
252  * - \ref SCIP_STAGE_TRANSFORMED
253  * - \ref SCIP_STAGE_INITPRESOLVE
254  * - \ref SCIP_STAGE_PRESOLVING
255  * - \ref SCIP_STAGE_EXITPRESOLVE
256  * - \ref SCIP_STAGE_PRESOLVED
257  * - \ref SCIP_STAGE_INITSOLVE
258  * - \ref SCIP_STAGE_SOLVING
259  * - \ref SCIP_STAGE_SOLVED
260  * - \ref SCIP_STAGE_EXITSOLVE
261  * - \ref SCIP_STAGE_FREETRANS
262  */
263 extern
265  SCIP* scip, /**< SCIP data structure */
266  SCIP_VAR* var, /**< transformed variable to catch event for */
267  SCIP_EVENTTYPE eventtype, /**< event type mask to select events to catch */
268  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
269  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
270  int* filterpos /**< pointer to store position of event filter entry, or NULL */
271  );
272 
273 /** drops an objective value or domain change event (stops to track event) on the given transformed variable
274  *
275  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
276  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
277  *
278  * @pre This method can be called if @p scip is in one of the following stages:
279  * - \ref SCIP_STAGE_TRANSFORMING
280  * - \ref SCIP_STAGE_TRANSFORMED
281  * - \ref SCIP_STAGE_INITPRESOLVE
282  * - \ref SCIP_STAGE_PRESOLVING
283  * - \ref SCIP_STAGE_EXITPRESOLVE
284  * - \ref SCIP_STAGE_PRESOLVED
285  * - \ref SCIP_STAGE_INITSOLVE
286  * - \ref SCIP_STAGE_SOLVING
287  * - \ref SCIP_STAGE_SOLVED
288  * - \ref SCIP_STAGE_EXITSOLVE
289  * - \ref SCIP_STAGE_FREETRANS
290  */
291 extern
293  SCIP* scip, /**< SCIP data structure */
294  SCIP_VAR* var, /**< transformed variable to drop event for */
295  SCIP_EVENTTYPE eventtype, /**< event type mask of dropped event */
296  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
297  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
298  int filterpos /**< position of event filter entry returned by SCIPcatchVarEvent(), or -1 */
299  );
300 
301 /** catches a row coefficient, constant, or side change event on the given row
302  *
303  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
304  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
305  *
306  * @pre This method can be called if @p scip is in one of the following stages:
307  * - \ref SCIP_STAGE_TRANSFORMING
308  * - \ref SCIP_STAGE_TRANSFORMED
309  * - \ref SCIP_STAGE_INITPRESOLVE
310  * - \ref SCIP_STAGE_PRESOLVING
311  * - \ref SCIP_STAGE_EXITPRESOLVE
312  * - \ref SCIP_STAGE_PRESOLVED
313  * - \ref SCIP_STAGE_INITSOLVE
314  * - \ref SCIP_STAGE_SOLVING
315  * - \ref SCIP_STAGE_SOLVED
316  * - \ref SCIP_STAGE_EXITSOLVE
317  * - \ref SCIP_STAGE_FREETRANS
318  */
319 extern
321  SCIP* scip, /**< SCIP data structure */
322  SCIP_ROW* row, /**< linear row to catch event for */
323  SCIP_EVENTTYPE eventtype, /**< event type mask to select events to catch */
324  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
325  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
326  int* filterpos /**< pointer to store position of event filter entry, or NULL */
327  );
328 
329 /** drops a row coefficient, constant, or side change event (stops to track event) on the given row
330  *
331  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
332  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
333  *
334  * @pre This method can be called if @p scip is in one of the following stages:
335  * - \ref SCIP_STAGE_TRANSFORMING
336  * - \ref SCIP_STAGE_TRANSFORMED
337  * - \ref SCIP_STAGE_INITPRESOLVE
338  * - \ref SCIP_STAGE_PRESOLVING
339  * - \ref SCIP_STAGE_EXITPRESOLVE
340  * - \ref SCIP_STAGE_PRESOLVED
341  * - \ref SCIP_STAGE_INITSOLVE
342  * - \ref SCIP_STAGE_SOLVING
343  * - \ref SCIP_STAGE_SOLVED
344  * - \ref SCIP_STAGE_EXITSOLVE
345  * - \ref SCIP_STAGE_FREETRANS
346  */
347 extern
349  SCIP* scip, /**< SCIP data structure */
350  SCIP_ROW* row, /**< linear row to drop event for */
351  SCIP_EVENTTYPE eventtype, /**< event type mask of dropped event */
352  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
353  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
354  int filterpos /**< position of event filter entry returned by SCIPcatchVarEvent(), or -1 */
355  );
356 
357 /**@} */
358 
359 #ifdef __cplusplus
360 }
361 #endif
362 
363 #endif
SCIP_RETCODE SCIPsetEventhdlrInitsol(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTINITSOL((*eventinitsol)))
Definition: scip_event.c:260
internal methods for branch and bound tree
SCIP_RETCODE SCIPcatchVarEvent(SCIP *scip, SCIP_VAR *var, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int *filterpos)
Definition: scip_event.c:422
int SCIPgetNEventhdlrs(SCIP *scip)
Definition: scip_event.c:326
SCIP_RETCODE SCIPsetEventhdlrExitsol(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTEXITSOL((*eventexitsol)))
Definition: scip_event.c:274
SCIP_RETCODE SCIPsetEventhdlrExit(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTEXIT((*eventexit)))
Definition: scip_event.c:246
SCIP_RETCODE SCIPincludeEventhdlrBasic(SCIP *scip, SCIP_EVENTHDLR **eventhdlrptr, const char *name, const char *desc, SCIP_DECL_EVENTEXEC((*eventexec)), SCIP_EVENTHDLRDATA *eventhdlrdata)
Definition: scip_event.c:172
SCIP_RETCODE SCIPcatchRowEvent(SCIP *scip, SCIP_ROW *row, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int *filterpos)
Definition: scip_event.c:508
SCIP_DECL_EVENTEXIT(EventhdlrNewSol::scip_exit)
struct SCIP_EventhdlrData SCIP_EVENTHDLRDATA
Definition: type_event.h:138
enum SCIP_Retcode SCIP_RETCODE
Definition: type_retcode.h:53
type definitions for return codes for SCIP methods
SCIP_EVENTHDLR * SCIPfindEventhdlr(SCIP *scip, const char *name)
Definition: scip_event.c:302
SCIP_RETCODE SCIPdropRowEvent(SCIP *scip, SCIP_ROW *row, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int filterpos)
Definition: scip_event.c:548
SCIP_DECL_EVENTINITSOL(EventhdlrNewSol::scip_initsol)
type definitions for LP management
SCIP_DECL_EVENTINIT(EventhdlrNewSol::scip_init)
SCIP_DECL_EVENTFREE(EventhdlrNewSol::scip_free)
SCIP_RETCODE SCIPsetEventhdlrFree(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTFREE((*eventfree)))
Definition: scip_event.c:218
SCIP_RETCODE SCIPsetEventhdlrCopy(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTCOPY((*eventcopy)))
Definition: scip_event.c:204
type definitions for SCIP&#39;s main datastructure
SCIP_RETCODE SCIPsetEventhdlrInit(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTINIT((*eventinit)))
Definition: scip_event.c:232
struct SCIP_EventData SCIP_EVENTDATA
Definition: type_event.h:155
internal miscellaneous methods
internal methods for global SCIP settings
SCIP main data structure.
type definitions for problem variables
type definitions for managing events
internal methods for problem variables
SCIP_RETCODE SCIPcatchEvent(SCIP *scip, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int *filterpos)
Definition: scip_event.c:354
SCIP_RETCODE SCIPincludeEventhdlr(SCIP *scip, const char *name, const char *desc, SCIP_DECL_EVENTCOPY((*eventcopy)), SCIP_DECL_EVENTFREE((*eventfree)), SCIP_DECL_EVENTINIT((*eventinit)), SCIP_DECL_EVENTEXIT((*eventexit)), SCIP_DECL_EVENTINITSOL((*eventinitsol)), SCIP_DECL_EVENTEXITSOL((*eventexitsol)), SCIP_DECL_EVENTDELETE((*eventdelete)), SCIP_DECL_EVENTEXEC((*eventexec)), SCIP_EVENTHDLRDATA *eventhdlrdata)
Definition: scip_event.c:131
methods for debugging
SCIP_RETCODE SCIPdropEvent(SCIP *scip, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int filterpos)
Definition: scip_event.c:388
SCIP_RETCODE SCIPdropVarEvent(SCIP *scip, SCIP_VAR *var, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int filterpos)
Definition: scip_event.c:468
datastructures for problem statistics
SCIP_EVENTHDLR ** SCIPgetEventhdlrs(SCIP *scip)
Definition: scip_event.c:315
internal methods for main solving loop and node processing
SCIP_RETCODE SCIPsetEventhdlrDelete(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTDELETE((*eventdelete)))
Definition: scip_event.c:288
SCIP_DECL_EVENTEXEC(EventhdlrNewSol::scip_exec)
SCIP_DECL_EVENTEXITSOL(EventhdlrNewSol::scip_exitsol)
#define SCIP_DECL_EVENTCOPY(x)
Definition: type_event.h:165
internal methods for constraints and constraint handlers
SCIP_DECL_EVENTDELETE(EventhdlrNewSol::scip_delete)
common defines and data types used in all packages of SCIP
uint64_t SCIP_EVENTTYPE
Definition: type_event.h:134