source: trunk/Cbc/src/CbcEventHandler.hpp @ 1943

Last change on this file since 1943 was 1943, checked in by forrest, 6 years ago

more options, copy statistics structure analysis
start coding of "switch" variables i.e. badly scaled ints or hi/lo
changes to allow more influence on small branch and bound
changes to get correct printout with threads

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.6 KB
Line 
1/*
2  Copyright (C) 2006, International Business Machines Corporation and others.
3  All Rights Reserved.
4
5  This code is licensed under the terms of the Eclipse Public License (EPL).
6
7  $Id: CbcEventHandler.hpp 1943 2013-07-21 09:05:45Z forrest $
8*/
9
10#ifndef CbcEventHandler_H
11#define CbcEventHandler_H
12
13/*! \file CbcEventHandler.hpp
14    \brief Event handling for cbc
15
16  This file contains the declaration of CbcEventHandler, used for event
17  handling in cbc.
18
19  The central method is CbcEventHandler::event(). The default semantics of
20  this call are `ask for the action to take in reponse to this event'. The
21  call is made at the point in the code where the event occurs (<i>e.g.</i>,
22  when a solution is found, or when a node is added to or removed from the
23  search tree). The return value specifies the action to perform in response
24  to the event (<i>e.g.</i>, continue, or stop).
25
26  This is a lazy class. Initially, it knows nothing about specific events,
27  and returns dfltAction_ for any event. This makes for a trivial constructor
28  and fast startup. The only place where the list of known events or actions
29  is hardwired is in the enum definitions for CbcEvent and CbcAction,
30  respectively.
31
32  At the first call to setAction, a map is created to hold (Event,Action)
33  pairs, and this map will be consulted ever after. Events not in the map
34  will still return the default value.
35
36  For serious extensions, derive a subclass and replace event() with a
37  function that suits you better.  The function has access to the CbcModel
38  via a pointer held in the CbcEventHandler object, and can do as much
39  thinking as it likes before returning an answer.  You can also print as
40  much information as you want. The model is held as a const, however, so
41  you can't alter reality.
42
43  The design of the class deliberately matches ClpEventHandler, so that other
44  solvers can participate in cbc without breaking the patterns set by
45  clp-specific code.
46
47*/
48
49#include <map>
50
51/* May well already be declared, but can't hurt. */
52
53class CbcModel ;
54
55/*
56  cvs/svn: $Id: CbcEventHandler.hpp 1943 2013-07-21 09:05:45Z forrest $
57*/
58
59/*! \class CbcEventHandler
60    \brief Base class for Cbc event handling.
61
62  Up front: We're not talking about unanticipated events here. We're talking
63  about anticipated events, in the sense that the code is going to make a call
64  to event() and is prepared to obey the return value that it receives.
65
66  The general pattern for usage is as follows:
67  <ol>
68    <li> Create a CbcEventHandler object. This will be initialised with a set
69         of default actions for every recognised event.
70
71    <li> Attach the event handler to the CbcModel object.
72
73    <li> When execution reaches the point where an event occurs, call the
74         event handler as CbcEventHandler::event(the event). The return value
75         will specify what the code should do in response to the event.
76  </ol>
77
78  The return value associated with an event can be changed at any time.
79*/
80
81class CbcEventHandler {
82
83public:
84
85    /*! \brief Events known to cbc */
86
87    enum CbcEvent { /*! Processing of the current node is complete. */
88        node = 200,
89        /*! A tree status interval has arrived. */
90        treeStatus,
91        /*! A solution has been found. */
92        solution,
93        /*! A heuristic solution has been found. */
94        heuristicSolution,
95        /*! A solution will be found unless user takes action (first check). */
96        beforeSolution1,
97        /*! A solution will be found unless user takes action (thorough check). */
98        beforeSolution2,
99        /*! After failed heuristic. */
100        afterHeuristic,
101        /*! On entry to small branch and bound. */
102        smallBranchAndBound,
103        /*! End of search. */
104        endSearch
105    } ;
106
107    /*! \brief Action codes returned by the event handler.
108
109        Specific values are chosen to match ClpEventHandler return codes.
110    */
111
112    enum CbcAction { /*! Continue --- no action required. */
113        noAction = -1,
114        /*! Stop --- abort the current run at the next opportunity. */
115        stop = 0,
116        /*! Restart --- restart branch-and-cut search; do not undo root node
117        processing.
118        */
119        restart,
120        /*! RestartRoot --- undo root node and start branch-and-cut afresh. */
121        restartRoot,
122        /*! Add special cuts. */
123        addCuts,
124        /*! Pretend solution never happened. */
125        killSolution,
126        /*! Take action on modified data. */
127        takeAction
128
129    } ;
130
131    /*! \brief Data type for event/action pairs */
132
133    typedef std::map<CbcEvent, CbcAction> eaMapPair ;
134
135
136    /*! \name Event Processing */
137    //@{
138
139    /*! \brief Return the action to be taken for an event.
140
141      Return the action that should be taken in response to the event passed as
142      the parameter. The default implementation simply reads a return code
143      from a map.
144    */
145    virtual CbcAction event(CbcEvent whichEvent) ;
146
147    /*! \brief Return the action to be taken for an event - and modify data.
148
149      Return the action that should be taken in response to the event passed as
150      the parameter. The default implementation simply reads a return code
151      from a map.
152    */
153    virtual CbcAction event(CbcEvent whichEvent, void * data) ;
154
155    //@}
156
157
158    /*! \name Constructors and destructors */
159    //@{
160
161    /*! \brief Default constructor. */
162
163    CbcEventHandler(CbcModel *model = 0 /* was NULL but 4.6 complains */) ;
164
165    /*! \brief Copy constructor. */
166
167    CbcEventHandler(const CbcEventHandler &orig) ;
168
169    /*! \brief Assignment. */
170
171    CbcEventHandler& operator=(const CbcEventHandler &rhs) ;
172
173    /*! \brief Clone (virtual) constructor. */
174
175    virtual CbcEventHandler* clone() const ;
176
177    /*! \brief Destructor. */
178
179    virtual ~CbcEventHandler() ;
180
181    //@}
182
183    /*! \name Set/Get methods */
184    //@{
185
186    /*! \brief Set model. */
187
188    inline void setModel(CbcModel *model) {
189        model_ = model ;
190    }
191
192    /*! \brief Get model. */
193
194    inline const CbcModel* getModel() const {
195        return model_ ;
196    }
197
198    /*! \brief Set the default action */
199
200    inline void setDfltAction(CbcAction action) {
201        dfltAction_ = action ;
202    }
203
204    /*! \brief Set the action code associated with an event */
205
206    inline void setAction(CbcEvent event, CbcAction action) {
207        if (eaMap_ == 0) {
208            eaMap_ = new eaMapPair ;
209        }
210        (*eaMap_)[event] = action ;
211    }
212
213    //@}
214
215
216protected:
217
218    /*! \name Data members
219
220       Protected (as opposed to private) to allow access by derived classes.
221    */
222    //@{
223
224    /*! \brief Pointer to associated CbcModel */
225
226    CbcModel *model_ ;
227
228    /*! \brief Default action */
229
230    CbcAction dfltAction_ ;
231
232    /*! \brief Pointer to a map that holds non-default event/action pairs */
233
234    eaMapPair *eaMap_ ;
235
236    //@}
237} ;
238
239#endif
240
Note: See TracBrowser for help on using the repository browser.