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-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 scip_event.h
26  * @ingroup PUBLICCOREAPI
27  * @brief public methods for event handler plugins and event handlers
28  * @author Tobias Achterberg
29  * @author Timo Berthold
30  * @author Thorsten Koch
31  * @author Alexander Martin
32  * @author Marc Pfetsch
33  * @author Kati Wolter
34  * @author Gregor Hendel
35  * @author Leona Gottwald
36  */
37 
38 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
39 
40 #ifndef __SCIP_SCIP_EVENT_H__
41 #define __SCIP_SCIP_EVENT_H__
42 
43 
44 #include "scip/def.h"
45 #include "scip/type_event.h"
46 #include "scip/type_lp.h"
47 #include "scip/type_retcode.h"
48 #include "scip/type_scip.h"
49 #include "scip/type_var.h"
50 
51 #ifdef __cplusplus
52 extern "C" {
53 #endif
54 
55 /**@addtogroup PublicEventHandlerMethods
56  *
57  * @{
58  */
59 
60 /** creates an event handler and includes it in SCIP
61  *
62  * @note method has all event handler callbacks as arguments and is thus changed every time a new
63  * callback is added in future releases; consider using SCIPincludeEventhdlrBasic() and setter functions
64  * if you seek for a method which is less likely to change in future releases
65  */
66 SCIP_EXPORT
68  SCIP* scip, /**< SCIP data structure */
69  const char* name, /**< name of event handler */
70  const char* desc, /**< description of event handler */
71  SCIP_DECL_EVENTCOPY ((*eventcopy)), /**< copy method of event handler or NULL if you don't want to copy your plugin into sub-SCIPs */
72  SCIP_DECL_EVENTFREE ((*eventfree)), /**< destructor of event handler */
73  SCIP_DECL_EVENTINIT ((*eventinit)), /**< initialize event handler */
74  SCIP_DECL_EVENTEXIT ((*eventexit)), /**< deinitialize event handler */
75  SCIP_DECL_EVENTINITSOL((*eventinitsol)), /**< solving process initialization method of event handler */
76  SCIP_DECL_EVENTEXITSOL((*eventexitsol)), /**< solving process deinitialization method of event handler */
77  SCIP_DECL_EVENTDELETE ((*eventdelete)), /**< free specific event data */
78  SCIP_DECL_EVENTEXEC ((*eventexec)), /**< execute event handler */
79  SCIP_EVENTHDLRDATA* eventhdlrdata /**< event handler data */
80  );
81 
82 /** creates an event handler and includes it in SCIP with all its non-fundamental callbacks set
83  * to NULL; if needed, non-fundamental callbacks can be set afterwards via setter functions
84  * SCIPsetEventhdlrCopy(), SCIPsetEventhdlrFree(), SCIPsetEventhdlrInit(), SCIPsetEventhdlrExit(),
85  * SCIPsetEventhdlrInitsol(), SCIPsetEventhdlrExitsol(), and SCIPsetEventhdlrDelete()
86  *
87  * @note if you want to set all callbacks with a single method call, consider using SCIPincludeEventhdlr() instead
88  */
89 SCIP_EXPORT
91  SCIP* scip, /**< SCIP data structure */
92  SCIP_EVENTHDLR** eventhdlrptr, /**< reference to an event handler, or NULL */
93  const char* name, /**< name of event handler */
94  const char* desc, /**< description of event handler */
95  SCIP_DECL_EVENTEXEC ((*eventexec)), /**< execute event handler */
96  SCIP_EVENTHDLRDATA* eventhdlrdata /**< event handler data */
97  );
98 
99 /** sets copy callback of the event handler */
100 SCIP_EXPORT
102  SCIP* scip, /**< scip instance */
103  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
104  SCIP_DECL_EVENTCOPY ((*eventcopy)) /**< copy callback of the event handler */
105  );
106 
107 /** sets deinitialization callback of the event handler */
108 SCIP_EXPORT
110  SCIP* scip, /**< scip instance */
111  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
112  SCIP_DECL_EVENTFREE ((*eventfree)) /**< deinitialization callback of the event handler */
113  );
114 
115 /** sets initialization callback of the event handler */
116 SCIP_EXPORT
118  SCIP* scip, /**< scip instance */
119  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
120  SCIP_DECL_EVENTINIT ((*eventinit)) /**< initialize event handler */
121  );
122 
123 /** sets deinitialization callback of the event handler */
124 SCIP_EXPORT
126  SCIP* scip, /**< scip instance */
127  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
128  SCIP_DECL_EVENTEXIT ((*eventexit)) /**< deinitialize event handler */
129  );
130 
131 /** sets solving process initialization callback of the event handler */
132 SCIP_EXPORT
134  SCIP* scip, /**< scip instance */
135  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
136  SCIP_DECL_EVENTINITSOL((*eventinitsol)) /**< solving process initialization callback of event handler */
137  );
138 
139 /** sets solving process deinitialization callback of the event handler */
140 SCIP_EXPORT
142  SCIP* scip, /**< scip instance */
143  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
144  SCIP_DECL_EVENTEXITSOL((*eventexitsol)) /**< solving process deinitialization callback of event handler */
145  );
146 
147 /** sets callback of the event handler to free specific event data */
148 SCIP_EXPORT
150  SCIP* scip, /**< scip instance */
151  SCIP_EVENTHDLR* eventhdlr, /**< event handler */
152  SCIP_DECL_EVENTDELETE ((*eventdelete)) /**< free specific event data */
153  );
154 
155 /** returns the event handler of the given name, or NULL if not existing */
156 SCIP_EXPORT
158  SCIP* scip, /**< SCIP data structure */
159  const char* name /**< name of event handler */
160  );
161 
162 /** returns the array of currently available event handlers */
163 SCIP_EXPORT
165  SCIP* scip /**< SCIP data structure */
166  );
167 
168 /** returns the number of currently available event handlers */
169 SCIP_EXPORT
171  SCIP* scip /**< SCIP data structure */
172  );
173 
174 /** @} */
175 
176 /**@addtogroup PublicEventMethods
177  *
178  * @{
179  */
180 
181 /** catches a global (not variable or row dependent) event
182  *
183  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
184  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
185  *
186  * @pre This method can be called if @p scip is in one of the following stages:
187  * - \ref SCIP_STAGE_TRANSFORMING
188  * - \ref SCIP_STAGE_TRANSFORMED
189  * - \ref SCIP_STAGE_INITPRESOLVE
190  * - \ref SCIP_STAGE_PRESOLVING
191  * - \ref SCIP_STAGE_EXITPRESOLVE
192  * - \ref SCIP_STAGE_PRESOLVED
193  * - \ref SCIP_STAGE_INITSOLVE
194  * - \ref SCIP_STAGE_SOLVING
195  * - \ref SCIP_STAGE_SOLVED
196  * - \ref SCIP_STAGE_EXITSOLVE
197  * - \ref SCIP_STAGE_FREETRANS
198  */
199 SCIP_EXPORT
201  SCIP* scip, /**< SCIP data structure */
202  SCIP_EVENTTYPE eventtype, /**< event type mask to select events to catch */
203  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
204  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
205  int* filterpos /**< pointer to store position of event filter entry, or NULL */
206  );
207 
208 /** drops a global event (stops to track event)
209  *
210  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
211  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
212  *
213  * @pre This method can be called if @p scip is in one of the following stages:
214  * - \ref SCIP_STAGE_TRANSFORMING
215  * - \ref SCIP_STAGE_TRANSFORMED
216  * - \ref SCIP_STAGE_INITPRESOLVE
217  * - \ref SCIP_STAGE_PRESOLVING
218  * - \ref SCIP_STAGE_EXITPRESOLVE
219  * - \ref SCIP_STAGE_PRESOLVED
220  * - \ref SCIP_STAGE_INITSOLVE
221  * - \ref SCIP_STAGE_SOLVING
222  * - \ref SCIP_STAGE_SOLVED
223  * - \ref SCIP_STAGE_EXITSOLVE
224  * - \ref SCIP_STAGE_FREETRANS
225  */
226 SCIP_EXPORT
228  SCIP* scip, /**< SCIP data structure */
229  SCIP_EVENTTYPE eventtype, /**< event type mask of dropped event */
230  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
231  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
232  int filterpos /**< position of event filter entry returned by SCIPcatchEvent(), or -1 */
233  );
234 
235 /** catches an objective value or domain change event on the given transformed variable
236  *
237  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
238  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
239  *
240  * @pre This method can be called if @p scip is in one of the following stages:
241  * - \ref SCIP_STAGE_TRANSFORMING
242  * - \ref SCIP_STAGE_TRANSFORMED
243  * - \ref SCIP_STAGE_INITPRESOLVE
244  * - \ref SCIP_STAGE_PRESOLVING
245  * - \ref SCIP_STAGE_EXITPRESOLVE
246  * - \ref SCIP_STAGE_PRESOLVED
247  * - \ref SCIP_STAGE_INITSOLVE
248  * - \ref SCIP_STAGE_SOLVING
249  * - \ref SCIP_STAGE_SOLVED
250  * - \ref SCIP_STAGE_EXITSOLVE
251  * - \ref SCIP_STAGE_FREETRANS
252  */
253 SCIP_EXPORT
255  SCIP* scip, /**< SCIP data structure */
256  SCIP_VAR* var, /**< transformed variable to catch event for */
257  SCIP_EVENTTYPE eventtype, /**< event type mask to select events to catch */
258  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
259  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
260  int* filterpos /**< pointer to store position of event filter entry, or NULL */
261  );
262 
263 /** drops an objective value or domain change event (stops to track event) on the given transformed variable
264  *
265  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
266  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
267  *
268  * @pre This method can be called if @p scip is in one of the following stages:
269  * - \ref SCIP_STAGE_TRANSFORMING
270  * - \ref SCIP_STAGE_TRANSFORMED
271  * - \ref SCIP_STAGE_INITPRESOLVE
272  * - \ref SCIP_STAGE_PRESOLVING
273  * - \ref SCIP_STAGE_EXITPRESOLVE
274  * - \ref SCIP_STAGE_PRESOLVED
275  * - \ref SCIP_STAGE_INITSOLVE
276  * - \ref SCIP_STAGE_SOLVING
277  * - \ref SCIP_STAGE_SOLVED
278  * - \ref SCIP_STAGE_EXITSOLVE
279  * - \ref SCIP_STAGE_FREETRANS
280  */
281 SCIP_EXPORT
283  SCIP* scip, /**< SCIP data structure */
284  SCIP_VAR* var, /**< transformed variable to drop event for */
285  SCIP_EVENTTYPE eventtype, /**< event type mask of dropped event */
286  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
287  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
288  int filterpos /**< position of event filter entry returned by SCIPcatchVarEvent(), or -1 */
289  );
290 
291 /** catches a row coefficient, constant, or side change event on the given row
292  *
293  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
294  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
295  *
296  * @pre This method can be called if @p scip is in one of the following stages:
297  * - \ref SCIP_STAGE_TRANSFORMING
298  * - \ref SCIP_STAGE_TRANSFORMED
299  * - \ref SCIP_STAGE_INITPRESOLVE
300  * - \ref SCIP_STAGE_PRESOLVING
301  * - \ref SCIP_STAGE_EXITPRESOLVE
302  * - \ref SCIP_STAGE_PRESOLVED
303  * - \ref SCIP_STAGE_INITSOLVE
304  * - \ref SCIP_STAGE_SOLVING
305  * - \ref SCIP_STAGE_SOLVED
306  * - \ref SCIP_STAGE_EXITSOLVE
307  * - \ref SCIP_STAGE_FREETRANS
308  */
309 SCIP_EXPORT
311  SCIP* scip, /**< SCIP data structure */
312  SCIP_ROW* row, /**< linear row to catch event for */
313  SCIP_EVENTTYPE eventtype, /**< event type mask to select events to catch */
314  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
315  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
316  int* filterpos /**< pointer to store position of event filter entry, or NULL */
317  );
318 
319 /** drops a row coefficient, constant, or side change event (stops to track event) on the given row
320  *
321  * @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
322  * SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
323  *
324  * @pre This method can be called if @p scip is in one of the following stages:
325  * - \ref SCIP_STAGE_TRANSFORMING
326  * - \ref SCIP_STAGE_TRANSFORMED
327  * - \ref SCIP_STAGE_INITPRESOLVE
328  * - \ref SCIP_STAGE_PRESOLVING
329  * - \ref SCIP_STAGE_EXITPRESOLVE
330  * - \ref SCIP_STAGE_PRESOLVED
331  * - \ref SCIP_STAGE_INITSOLVE
332  * - \ref SCIP_STAGE_SOLVING
333  * - \ref SCIP_STAGE_SOLVED
334  * - \ref SCIP_STAGE_EXITSOLVE
335  * - \ref SCIP_STAGE_FREETRANS
336  */
337 SCIP_EXPORT
339  SCIP* scip, /**< SCIP data structure */
340  SCIP_ROW* row, /**< linear row to drop event for */
341  SCIP_EVENTTYPE eventtype, /**< event type mask of dropped event */
342  SCIP_EVENTHDLR* eventhdlr, /**< event handler to process events with */
343  SCIP_EVENTDATA* eventdata, /**< event data to pass to the event handler when processing this event */
344  int filterpos /**< position of event filter entry returned by SCIPcatchVarEvent(), or -1 */
345  );
346 
347 /**@} */
348 
349 #ifdef __cplusplus
350 }
351 #endif
352 
353 #endif
SCIP_RETCODE SCIPsetEventhdlrInitsol(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTINITSOL((*eventinitsol)))
Definition: scip_event.c:192
SCIP_RETCODE SCIPcatchVarEvent(SCIP *scip, SCIP_VAR *var, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int *filterpos)
Definition: scip_event.c:354
int SCIPgetNEventhdlrs(SCIP *scip)
Definition: scip_event.c:258
SCIP_RETCODE SCIPsetEventhdlrExitsol(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTEXITSOL((*eventexitsol)))
Definition: scip_event.c:206
SCIP_RETCODE SCIPsetEventhdlrExit(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTEXIT((*eventexit)))
Definition: scip_event.c:178
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:104
SCIP_RETCODE SCIPcatchRowEvent(SCIP *scip, SCIP_ROW *row, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int *filterpos)
Definition: scip_event.c:440
SCIP_DECL_EVENTEXIT(EventhdlrNewSol::scip_exit)
struct SCIP_EventhdlrData SCIP_EVENTHDLRDATA
Definition: type_event.h:155
enum SCIP_Retcode SCIP_RETCODE
Definition: type_retcode.h:63
type definitions for return codes for SCIP methods
SCIP_EVENTHDLR * SCIPfindEventhdlr(SCIP *scip, const char *name)
Definition: scip_event.c:234
SCIP_RETCODE SCIPdropRowEvent(SCIP *scip, SCIP_ROW *row, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int filterpos)
Definition: scip_event.c:480
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:150
SCIP_RETCODE SCIPsetEventhdlrCopy(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTCOPY((*eventcopy)))
Definition: scip_event.c:136
type definitions for SCIP&#39;s main datastructure
SCIP_RETCODE SCIPsetEventhdlrInit(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTINIT((*eventinit)))
Definition: scip_event.c:164
struct SCIP_EventData SCIP_EVENTDATA
Definition: type_event.h:173
type definitions for problem variables
type definitions for managing events
SCIP_RETCODE SCIPcatchEvent(SCIP *scip, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int *filterpos)
Definition: scip_event.c:286
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:63
SCIP_RETCODE SCIPdropEvent(SCIP *scip, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int filterpos)
Definition: scip_event.c:320
SCIP_RETCODE SCIPdropVarEvent(SCIP *scip, SCIP_VAR *var, SCIP_EVENTTYPE eventtype, SCIP_EVENTHDLR *eventhdlr, SCIP_EVENTDATA *eventdata, int filterpos)
Definition: scip_event.c:400
SCIP_EVENTHDLR ** SCIPgetEventhdlrs(SCIP *scip)
Definition: scip_event.c:247
SCIP_RETCODE SCIPsetEventhdlrDelete(SCIP *scip, SCIP_EVENTHDLR *eventhdlr, SCIP_DECL_EVENTDELETE((*eventdelete)))
Definition: scip_event.c:220
SCIP_DECL_EVENTEXEC(EventhdlrNewSol::scip_exec)
SCIP_DECL_EVENTEXITSOL(EventhdlrNewSol::scip_exitsol)
#define SCIP_DECL_EVENTCOPY(x)
Definition: type_event.h:183
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:151