Scippy

SCIP

Solving Constraint Integer Programs

objheur.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-2014 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 email to scip@zib.de. */
13 /* */
14 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
15 
16 /**@file objheur.h
17  * @brief C++ wrapper for primal heuristics
18  * @author Tobias Achterberg
19  */
20 
21 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
22 
23 #ifndef __SCIP_OBJHEUR_H__
24 #define __SCIP_OBJHEUR_H__
25 
26 #include <cstring>
27 
28 #include "scip/scip.h"
29 #include "objscip/objcloneable.h"
30 
31 namespace scip
32 {
33 
34 /** @brief C++ wrapper for primal heuristics
35  *
36  * This class defines the interface for primal heuristics implemented in C++. Note that there is a pure virtual
37  * function (this function has to be implemented). This function is: scip_exec().
38  *
39  * - \ref HEUR "Instructions for implementing a primal heuristic"
40  * - \ref PRIMALHEURISTICS "List of available primal heuristics"
41  * - \ref type_heur.h "Corresponding C interface"
42  */
43 class ObjHeur : public ObjCloneable
44 {
45 public:
46  /*lint --e{1540}*/
47 
48  /** SCIP data structure */
50 
51  /** name of the primal heuristic */
52  char* scip_name_;
53 
54  /** description of the primal heuristic */
55  char* scip_desc_;
56 
57  /** display character of primal heuristic */
58  const char scip_dispchar_;
59 
60  /** default priority of the primal heuristic */
61  const int scip_priority_;
62 
63  /** frequency for calling primal heuristic */
64  const int scip_freq_;
65 
66  /** frequency offset for calling primal heuristic */
67  const int scip_freqofs_;
68 
69  /** maximal depth level to call heuristic at (-1: no limit) */
70  const int scip_maxdepth_;
71 
72  /** positions in the node solving loop where heuristic should be executed */
73  const unsigned int scip_timingmask_;
74 
75  /** does the heuristic use a secondary SCIP instance? */
77 
78  /** default constructor */
80  SCIP* scip, /**< SCIP data structure */
81  const char* name, /**< name of primal heuristic */
82  const char* desc, /**< description of primal heuristic */
83  char dispchar, /**< display character of primal heuristic */
84  int priority, /**< priority of the primal heuristic */
85  int freq, /**< frequency for calling primal heuristic */
86  int freqofs, /**< frequency offset for calling primal heuristic */
87  int maxdepth, /**< maximal depth level to call heuristic at (-1: no limit) */
88  unsigned int timingmask, /**< positions in the node solving loop where heuristic should be executed;
89  * see definition of SCIP_HeurTiming for possible values */
90  SCIP_Bool usessubscip /**< does the heuristic use a secondary SCIP instance? */
91  )
92  : scip_(scip),
93  scip_name_(0),
94  scip_desc_(0),
95  scip_dispchar_(dispchar),
96  scip_priority_(priority),
97  scip_freq_(freq),
98  scip_freqofs_(freqofs),
99  scip_maxdepth_(maxdepth),
100  scip_timingmask_(timingmask),
101  scip_usessubscip_(usessubscip)
102  {
103  /* the macro SCIPduplicateMemoryArray does not need the first argument: */
104  SCIP_CALL_ABORT( SCIPduplicateMemoryArray(scip_, &scip_name_, name, std::strlen(name)+1) );
105  SCIP_CALL_ABORT( SCIPduplicateMemoryArray(scip_, &scip_desc_, desc, std::strlen(desc)+1) );
106  }
107 
108  /** destructor */
109  virtual ~ObjHeur()
110  {
111  /* the macro SCIPfreeMemoryArray does not need the first argument: */
112  /*lint --e{64}*/
115  }
116 
117  /** destructor of primal heuristic to free user data (called when SCIP is exiting)
118  *
119  * @see SCIP_DECL_HEURFREE(x) in @ref type_heur.h
120  */
121  virtual SCIP_DECL_HEURFREE(scip_free)
122  { /*lint --e{715}*/
123  return SCIP_OKAY;
124  }
125 
126  /** initialization method of primal heuristic (called after problem was transformed)
127  *
128  * @see SCIP_DECL_HEURINIT(x) in @ref type_heur.h
129  */
130  virtual SCIP_DECL_HEURINIT(scip_init)
131  { /*lint --e{715}*/
132  return SCIP_OKAY;
133  }
134 
135  /** deinitialization method of primal heuristic (called before transformed problem is freed)
136  *
137  * @see SCIP_DECL_HEUREXIT(x) in @ref type_heur.h
138  */
139  virtual SCIP_DECL_HEUREXIT(scip_exit)
140  { /*lint --e{715}*/
141  return SCIP_OKAY;
142  }
143 
144  /** solving process initialization method of primal heuristic (called when branch and bound process is about to begin)
145  *
146  * @see SCIP_DECL_HEURINITSOL(x) in @ref type_heur.h
147  */
148  virtual SCIP_DECL_HEURINITSOL(scip_initsol)
149  { /*lint --e{715}*/
150  return SCIP_OKAY;
151  }
152 
153  /** solving process deinitialization method of primal heuristic (called before branch and bound process data is freed)
154  *
155  * @see SCIP_DECL_HEUREXITSOL(x) in @ref type_heur.h
156  */
157  virtual SCIP_DECL_HEUREXITSOL(scip_exitsol)
158  { /*lint --e{715}*/
159  return SCIP_OKAY;
160  }
161 
162  /** execution method of primal heuristic
163  *
164  * @see SCIP_DECL_HEUREXEC(x) in @ref type_heur.h
165  */
166  virtual SCIP_DECL_HEUREXEC(scip_exec) = 0;
167 };
168 
169 } /* namespace scip */
170 
171 
172 
173 /** creates the primal heuristic for the given primal heuristic object and includes it in SCIP
174  *
175  * The method should be called in one of the following ways:
176  *
177  * 1. The user is resposible of deleting the object:
178  * SCIP_CALL( SCIPcreate(&scip) );
179  * ...
180  * MyHeur* myheur = new MyHeur(...);
181  * SCIP_CALL( SCIPincludeObjHeur(scip, &myheur, FALSE) );
182  * ...
183  * SCIP_CALL( SCIPfree(&scip) );
184  * delete myheur; // delete heur AFTER SCIPfree() !
185  *
186  * 2. The object pointer is passed to SCIP and deleted by SCIP in the SCIPfree() call:
187  * SCIP_CALL( SCIPcreate(&scip) );
188  * ...
189  * SCIP_CALL( SCIPincludeObjHeur(scip, new MyHeur(...), TRUE) );
190  * ...
191  * SCIP_CALL( SCIPfree(&scip) ); // destructor of MyHeur is called here
192  */
193 extern
195  SCIP* scip, /**< SCIP data structure */
196  scip::ObjHeur* objheur, /**< primal heuristic object */
197  SCIP_Bool deleteobject /**< should the primal heuristic object be deleted when heuristic is freed? */
198  );
199 
200 /** returns the heur object of the given name, or 0 if not existing */
201 extern
203  SCIP* scip, /**< SCIP data structure */
204  const char* name /**< name of primal heuristic */
205  );
206 
207 /** returns the heur object for the given primal heuristic */
208 extern
210  SCIP* scip, /**< SCIP data structure */
211  SCIP_HEUR* heur /**< primal heuristic */
212  );
213 
214 #endif
215