1    	/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
2    	/*                                                                           */
3    	/*                  This file is part of the program and library             */
4    	/*         SCIP --- Solving Constraint Integer Programs                      */
5    	/*                                                                           */
6    	/*  Copyright (c) 2002-2023 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   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 */
59   	   SCIP* scip_;
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 */
83   	   const SCIP_HEURTIMING scip_timingmask_;
84   	
85   	   /** does the heuristic use a secondary SCIP instance? */
86   	   const SCIP_Bool scip_usessubscip_;
87   	
88   	   /** default constructor */
89   	   ObjHeur(
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 */
126  	   ObjHeur(ObjHeur&& o)
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
234  	SCIP_RETCODE SCIPincludeObjHeur(
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
242  	scip::ObjHeur* SCIPfindObjHeur(
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
249  	scip::ObjHeur* SCIPgetObjHeur(
250  	   SCIP*                 scip,               /**< SCIP data structure */
251  	   SCIP_HEUR*            heur                /**< primal heuristic */
252  	   );
253  	
254  	#endif
255