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 2002-2022 Zuse Institute Berlin */
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 objheur.h
26  * @brief C++ wrapper for primal heuristics
27  * @author Tobias Achterberg
28  */
29 
30 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
31 
32 #ifndef __SCIP_OBJHEUR_H__
33 #define __SCIP_OBJHEUR_H__
34 
35 #include <cstring>
36 #include <utility>
37 
38 #include "scip/scip.h"
39 #include "objscip/objcloneable.h"
40 
41 namespace scip
42 {
43 
44 /** @brief C++ wrapper for primal heuristics
45  *
46  * This class defines the interface for primal heuristics implemented in C++. Note that there is a pure virtual
47  * function (this function has to be implemented). This function is: scip_exec().
48  *
49  * - \ref HEUR "Instructions for implementing a primal heuristic"
50  * - \ref PRIMALHEURISTICS "List of available primal heuristics"
51  * - \ref type_heur.h "Corresponding C interface"
52  */
53 class ObjHeur : public ObjCloneable
54 {
55 public:
56  /*lint --e{1540}*/
57 
58  /** SCIP data structure */
60 
61  /** name of the primal heuristic */
62  char* scip_name_;
63 
64  /** description of the primal heuristic */
65  char* scip_desc_;
66 
67  /** display character of primal heuristic */
68  const char scip_dispchar_;
69 
70  /** default priority of the primal heuristic */
71  const int scip_priority_;
72 
73  /** frequency for calling primal heuristic */
74  const int scip_freq_;
75 
76  /** frequency offset for calling primal heuristic */
77  const int scip_freqofs_;
78 
79  /** maximal depth level to call heuristic at (-1: no limit) */
80  const int scip_maxdepth_;
81 
82  /** positions in the node solving loop where heuristic should be executed */
84 
85  /** does the heuristic use a secondary SCIP instance? */
87 
88  /** default constructor */
90  SCIP* scip, /**< SCIP data structure */
91  const char* name, /**< name of primal heuristic */
92  const char* desc, /**< description of primal heuristic */
93  char dispchar, /**< display character of primal heuristic */
94  int priority, /**< priority of the primal heuristic */
95  int freq, /**< frequency for calling primal heuristic */
96  int freqofs, /**< frequency offset for calling primal heuristic */
97  int maxdepth, /**< maximal depth level to call heuristic at (-1: no limit) */
98  SCIP_HEURTIMING timingmask, /**< positions in the node solving loop where heuristic should be executed;
99  * see definition of SCIP_HEURTIMING for possible values */
100  SCIP_Bool usessubscip /**< does the heuristic use a secondary SCIP instance? */
101  )
102  : scip_(scip),
103  scip_name_(0),
104  scip_desc_(0),
105  scip_dispchar_(dispchar),
106  scip_priority_(priority),
107  scip_freq_(freq),
108  scip_freqofs_(freqofs),
109  scip_maxdepth_(maxdepth),
110  scip_timingmask_(timingmask),
111  scip_usessubscip_(usessubscip)
112  {
113  /* the macro SCIPduplicateMemoryArray does not need the first argument: */
114  SCIP_CALL_ABORT( SCIPduplicateMemoryArray(scip_, &scip_name_, name, std::strlen(name)+1) );
115  SCIP_CALL_ABORT( SCIPduplicateMemoryArray(scip_, &scip_desc_, desc, std::strlen(desc)+1) );
116  }
117 
118  /** copy constructor */
119  ObjHeur(const ObjHeur& o)
120  : ObjHeur(o.scip_, o.scip_name_, o.scip_desc_, o.scip_dispchar_, o.scip_priority_, o.scip_freq_, o.scip_freqofs_,
121  o.scip_maxdepth_, o.scip_timingmask_, o.scip_usessubscip_)
122  {
123  }
124 
125  /** move constructor */
127  : scip_(o.scip_),
128  scip_name_(0),
129  scip_desc_(0),
130  scip_dispchar_(o.scip_dispchar_),
131  scip_priority_(o.scip_priority_),
132  scip_freq_(o.scip_freq_),
133  scip_freqofs_(o.scip_freqofs_),
134  scip_maxdepth_(o.scip_maxdepth_),
135  scip_timingmask_(o.scip_timingmask_),
136  scip_usessubscip_(o.scip_usessubscip_)
137  {
138  std::swap(scip_name_, o.scip_name_);
139  std::swap(scip_desc_, o.scip_desc_);
140  }
141 
142  /** destructor */
143  virtual ~ObjHeur()
144  {
145  /* the macro SCIPfreeMemoryArray does not need the first argument: */
146  /*lint --e{64}*/
147  SCIPfreeMemoryArray(scip_, &scip_name_);
148  SCIPfreeMemoryArray(scip_, &scip_desc_);
149  }
150 
151  /** assignment of polymorphic classes causes slicing and is therefore disabled. */
152  ObjHeur& operator=(const ObjHeur& o) = delete;
153 
154  /** assignment of polymorphic classes causes slicing and is therefore disabled. */
155  ObjHeur& operator=(ObjHeur&& o) = delete;
156 
157  /** destructor of primal heuristic to free user data (called when SCIP is exiting)
158  *
159  * @see SCIP_DECL_HEURFREE(x) in @ref type_heur.h
160  */
161  virtual SCIP_DECL_HEURFREE(scip_free)
162  { /*lint --e{715}*/
163  return SCIP_OKAY;
164  }
165 
166  /** initialization method of primal heuristic (called after problem was transformed)
167  *
168  * @see SCIP_DECL_HEURINIT(x) in @ref type_heur.h
169  */
170  virtual SCIP_DECL_HEURINIT(scip_init)
171  { /*lint --e{715}*/
172  return SCIP_OKAY;
173  }
174 
175  /** deinitialization method of primal heuristic (called before transformed problem is freed)
176  *
177  * @see SCIP_DECL_HEUREXIT(x) in @ref type_heur.h
178  */
179  virtual SCIP_DECL_HEUREXIT(scip_exit)
180  { /*lint --e{715}*/
181  return SCIP_OKAY;
182  }
183 
184  /** solving process initialization method of primal heuristic (called when branch and bound process is about to begin)
185  *
186  * @see SCIP_DECL_HEURINITSOL(x) in @ref type_heur.h
187  */
188  virtual SCIP_DECL_HEURINITSOL(scip_initsol)
189  { /*lint --e{715}*/
190  return SCIP_OKAY;
191  }
192 
193  /** solving process deinitialization method of primal heuristic (called before branch and bound process data is freed)
194  *
195  * @see SCIP_DECL_HEUREXITSOL(x) in @ref type_heur.h
196  */
197  virtual SCIP_DECL_HEUREXITSOL(scip_exitsol)
198  { /*lint --e{715}*/
199  return SCIP_OKAY;
200  }
201 
202  /** execution method of primal heuristic
203  *
204  * @see SCIP_DECL_HEUREXEC(x) in @ref type_heur.h
205  */
206  virtual SCIP_DECL_HEUREXEC(scip_exec) = 0;
207 };
208 
209 } /* namespace scip */
210 
211 
212 
213 /** creates the primal heuristic for the given primal heuristic object and includes it in SCIP
214  *
215  * The method should be called in one of the following ways:
216  *
217  * 1. The user is resposible of deleting the object:
218  * SCIP_CALL( SCIPcreate(&scip) );
219  * ...
220  * MyHeur* myheur = new MyHeur(...);
221  * SCIP_CALL( SCIPincludeObjHeur(scip, &myheur, FALSE) );
222  * ...
223  * SCIP_CALL( SCIPfree(&scip) );
224  * delete myheur; // delete heur AFTER SCIPfree() !
225  *
226  * 2. The object pointer is passed to SCIP and deleted by SCIP in the SCIPfree() call:
227  * SCIP_CALL( SCIPcreate(&scip) );
228  * ...
229  * SCIP_CALL( SCIPincludeObjHeur(scip, new MyHeur(...), TRUE) );
230  * ...
231  * SCIP_CALL( SCIPfree(&scip) ); // destructor of MyHeur is called here
232  */
233 SCIP_EXPORT
235  SCIP* scip, /**< SCIP data structure */
236  scip::ObjHeur* objheur, /**< primal heuristic object */
237  SCIP_Bool deleteobject /**< should the primal heuristic object be deleted when heuristic is freed? */
238  );
239 
240 /** returns the heur object of the given name, or 0 if not existing */
241 SCIP_EXPORT
243  SCIP* scip, /**< SCIP data structure */
244  const char* name /**< name of primal heuristic */
245  );
246 
247 /** returns the heur object for the given primal heuristic */
248 SCIP_EXPORT
250  SCIP* scip, /**< SCIP data structure */
251  SCIP_HEUR* heur /**< primal heuristic */
252  );
253 
254 #endif
ObjHeur(const ObjHeur &o)
Definition: objheur.h:119
ObjHeur(ObjHeur &&o)
Definition: objheur.h:126
const int scip_priority_
Definition: objheur.h:71
#define SCIPduplicateMemoryArray(scip, ptr, source, num)
Definition: scip_mem.h:76
C++ wrapper for primal heuristics.
Definition: objheur.h:53
#define SCIPfreeMemoryArray(scip, ptr)
Definition: scip_mem.h:80
unsigned int SCIP_HEURTIMING
Definition: type_timing.h:106
SCIP_RETCODE SCIPincludeObjHeur(SCIP *scip, scip::ObjHeur *objheur, SCIP_Bool deleteobject)
Definition: objheur.cpp:204
virtual SCIP_DECL_HEURINITSOL(scip_initsol)
Definition: objheur.h:188
enum SCIP_Retcode SCIP_RETCODE
Definition: type_retcode.h:63
const SCIP_Bool scip_usessubscip_
Definition: objheur.h:86
const int scip_freqofs_
Definition: objheur.h:77
scip::ObjHeur * SCIPfindObjHeur(SCIP *scip, const char *name)
Definition: objheur.cpp:233
definition of base class for all clonable classes
virtual SCIP_DECL_HEURINIT(scip_init)
Definition: objheur.h:170
const int scip_freq_
Definition: objheur.h:74
virtual ~ObjHeur()
Definition: objheur.h:143
const int scip_maxdepth_
Definition: objheur.h:80
virtual SCIP_DECL_HEURFREE(scip_free)
Definition: objheur.h:161
scip::ObjHeur * SCIPgetObjHeur(SCIP *scip, SCIP_HEUR *heur)
Definition: objheur.cpp:252
virtual SCIP_DECL_HEUREXIT(scip_exit)
Definition: objheur.h:179
#define SCIP_Bool
Definition: def.h:93
ObjHeur & operator=(const ObjHeur &o)=delete
SCIP * scip_
Definition: objheur.h:59
const char scip_dispchar_
Definition: objheur.h:68
char * scip_desc_
Definition: objheur.h:65
ObjHeur(SCIP *scip, const char *name, const char *desc, char dispchar, int priority, int freq, int freqofs, int maxdepth, SCIP_HEURTIMING timingmask, SCIP_Bool usessubscip)
Definition: objheur.h:89
Definition of base class for all clonable classes.
Definition: objcloneable.h:47
virtual SCIP_DECL_HEUREXITSOL(scip_exitsol)
Definition: objheur.h:197
char * scip_name_
Definition: objheur.h:62
virtual SCIP_DECL_HEUREXEC(scip_exec)=0
#define SCIP_CALL_ABORT(x)
Definition: def.h:372
const SCIP_HEURTIMING scip_timingmask_
Definition: objheur.h:83
SCIP callable library.