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   objprop.h
26   	 * @brief  C++ wrapper for propagators
27   	 * @author Tobias Achterberg
28   	 */
29   	
30   	/*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
31   	
32   	#ifndef __SCIP_OBJPROP_H__
33   	#define __SCIP_OBJPROP_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 propagators
45   	 *
46   	 *  This class defines the interface for propagators 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 PROP "Instructions for implementing a propagator"
50   	 *  - \ref PROPAGATORS "List of available propagators"
51   	 *  - \ref type_prop.h "Corresponding C interface"
52   	 */
53   	class ObjProp : public ObjCloneable
54   	{
55   	public:
56   	   /*lint --e{1540}*/
57   	
58   	   /** SCIP data structure */
59   	   SCIP* scip_;
60   	
61   	   /** name of the propagator */
62   	   char* scip_name_;
63   	
64   	   /** description of the propagator */
65   	   char* scip_desc_;
66   	
67   	   /** default priority of the propagator */
68   	   const int scip_priority_;
69   	
70   	   /** frequency for calling propagator */
71   	   const int scip_freq_;
72   	
73   	   /** should propagator be delayed, if other propagators found reductions? */
74   	   const SCIP_Bool scip_delay_;
75   	
76   	   /** positions in the node solving loop where propagator should be executed */
77   	   const SCIP_PROPTIMING scip_timingmask_;
78   	
79   	   /** default presolving priority of the propagator */
80   	   const int scip_presol_priority_;
81   	
82   	   /** frequency for calling propagator */
83   	   const int scip_presol_maxrounds_;
84   	
85   	   /**< timing mask of the propagator's presolving method */
86   	   const SCIP_PRESOLTIMING scip_presol_timing_;
87   	
88   	
89   	   /** default constructor */
90   	   ObjProp(
91   	      SCIP*              scip,               /**< SCIP data structure */
92   	      const char*        name,               /**< name of propagator */
93   	      const char*        desc,               /**< description of propagator */
94   	      int                priority,           /**< priority of the propagator */
95   	      int                freq,               /**< frequency for calling propagator */
96   	      SCIP_Bool          delay,              /**< should propagator be delayed, if other propagators found reductions? */
97   	      SCIP_PROPTIMING    timingmask,         /**< positions in the node solving loop where propagator should be executed */
98   	      int                presolpriority,     /**< presolving priority of the propagator (>= 0: before, < 0: after constraint handlers) */
99   	      int                presolmaxrounds,    /**< maximal number of presolving rounds the propagator participates in (-1: no limit) */
100  	      SCIP_PRESOLTIMING  presoltiming        /**< timing mask of the propagator's presolving method */
101  	      )
102  	      : scip_(scip),
103  	        scip_name_(0),
104  	        scip_desc_(0),
105  	        scip_priority_(priority),
106  	        scip_freq_(freq),
107  	        scip_delay_(delay),
108  	        scip_timingmask_(timingmask),
109  	        scip_presol_priority_(presolpriority),
110  	        scip_presol_maxrounds_(presolmaxrounds),
111  	        scip_presol_timing_(presoltiming)
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  	   ObjProp(const ObjProp& o)
120  	       : ObjProp(o.scip_, o.scip_name_, o.scip_desc_, o.scip_priority_, o.scip_freq_, o.scip_delay_, o.scip_timingmask_,
121  	                 o.scip_presol_priority_, o.scip_presol_maxrounds_, o.scip_presol_timing_)
122  	   {
123  	   }
124  	
125  	   /** move constructor */
126  	   ObjProp(ObjProp&& o)
127  	       : scip_(o.scip_),
128  	         scip_name_(0),
129  	         scip_desc_(0),
130  	         scip_priority_(o.scip_priority_),
131  	         scip_freq_(o.scip_freq_),
132  	         scip_delay_(o.scip_delay_),
133  	         scip_timingmask_(o.scip_timingmask_),
134  	         scip_presol_priority_(o.scip_presol_priority_),
135  	         scip_presol_maxrounds_(o.scip_presol_maxrounds_),
136  	         scip_presol_timing_(o.scip_presol_timing_)
137  	   {
138  	      std::swap(scip_name_, o.scip_name_);
139  	      std::swap(scip_desc_, o.scip_desc_);
140  	   }
141  	
142  	   /** destructor */
143  	   virtual ~ObjProp()
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  	   ObjProp& operator=(const ObjProp& o) = delete;
153  	
154  	   /** assignment of polymorphic classes causes slicing and is therefore disabled. */
155  	   ObjProp& operator=(ObjProp&& o) = delete;
156  	
157  	   /** destructor of propagator to free user data (called when SCIP is exiting)
158  	    *
159  	    *  @see SCIP_DECL_PROPFREE(x) in @ref type_prop.h
160  	    */
161  	   virtual SCIP_DECL_PROPFREE(scip_free)
162  	   {  /*lint --e{715}*/
163  	      return SCIP_OKAY;
164  	   }
165  	
166  	   /** initialization method of propagator (called after problem was transformed)
167  	    *
168  	    *  @see SCIP_DECL_PROPINIT(x) in @ref type_prop.h
169  	    */
170  	   virtual SCIP_DECL_PROPINIT(scip_init)
171  	   {  /*lint --e{715}*/
172  	      return SCIP_OKAY;
173  	   }
174  	
175  	   /** deinitialization method of propagator (called before transformed problem is freed)
176  	    *
177  	    *  @see SCIP_DECL_PROPEXIT(x) in @ref type_prop.h
178  	    */
179  	   virtual SCIP_DECL_PROPEXIT(scip_exit)
180  	   {  /*lint --e{715}*/
181  	      return SCIP_OKAY;
182  	   }
183  	
184  	   /** presolving initialization method of propagator (called when presolving is about to begin)
185  	    *
186  	    *  @see SCIP_DECL_PROPINITPRE(x) in @ref type_prop.h
187  	    */
188  	   virtual SCIP_DECL_PROPINITPRE(scip_initpre)
189  	   {  /*lint --e{715}*/
190  	      return SCIP_OKAY;
191  	   }
192  	
193  	   /** presolving deinitialization method of propagator (called after presolving has been finished)
194  	    *
195  	    *  @see SCIP_DECL_PROPEXITPRE(x) in @ref type_prop.h
196  	    */
197  	   virtual SCIP_DECL_PROPEXITPRE(scip_exitpre)
198  	   {  /*lint --e{715}*/
199  	      return SCIP_OKAY;
200  	   }
201  	
202  	   /** solving process initialization method of propagator (called when branch and bound process is about to begin)
203  	    *
204  	    *  @see SCIP_DECL_PROPINITSOL(x) in @ref type_prop.h
205  	    */
206  	   virtual SCIP_DECL_PROPINITSOL(scip_initsol)
207  	   {  /*lint --e{715}*/
208  	      return SCIP_OKAY;
209  	   }
210  	
211  	   /** solving process deinitialization method of propagator (called before branch and bound process data is freed)
212  	    *
213  	    *  @see SCIP_DECL_PROPEXITSOL(x) in @ref type_prop.h
214  	    */
215  	   virtual SCIP_DECL_PROPEXITSOL(scip_exitsol)
216  	   {  /*lint --e{715}*/
217  	      return SCIP_OKAY;
218  	   }
219  	
220  	   /** presolving method of propagator
221  	    *
222  	    *  @see SCIP_DECL_PROPPRESOL(x) in @ref type_prop.h
223  	    */
224  	   virtual SCIP_DECL_PROPPRESOL(scip_presol)
225  	   {  /*lint --e{715}*/
226  	      assert(result != NULL);
227  	      *result = SCIP_DIDNOTRUN;
228  	      return SCIP_OKAY;
229  	   }
230  	
231  	   /** execution method of propagator
232  	    *
233  	    *  @see SCIP_DECL_PROPEXEC(x) in @ref type_prop.h
234  	    */
235  	   virtual SCIP_DECL_PROPEXEC(scip_exec) = 0;
236  	
237  	   /** propagation conflict resolving method of propagator
238  	    *
239  	    *  @see SCIP_DECL_PROPRESPROP(x) in @ref type_prop.h
240  	    */
241  	   virtual SCIP_DECL_PROPRESPROP(scip_resprop)
242  	   {  /*lint --e{715}*/
243  	
244  	      /* set result pointer to indicate the propagation was not resolved */
245  	      assert(result != NULL);
246  	      (*result) = SCIP_DIDNOTFIND;
247  	
248  	      return SCIP_OKAY;
249  	   }
250  	};
251  	
252  	} /* namespace scip */
253  	
254  	
255  	
256  	/** creates the propagator for the given propagator object and includes it in SCIP
257  	 *
258  	 *  The method should be called in one of the following ways:
259  	 *
260  	 *   1. The user is resposible of deleting the object:
261  	 *       SCIP_CALL( SCIPcreate(&scip) );
262  	 *       ...
263  	 *       MyProp* myprop = new MyProp(...);
264  	 *       SCIP_CALL( SCIPincludeObjProp(scip, &myprop, FALSE) );
265  	 *       ...
266  	 *       SCIP_CALL( SCIPfree(&scip) );
267  	 *       delete myprop;    // delete prop AFTER SCIPfree() !
268  	 *
269  	 *   2. The object pointer is passed to SCIP and deleted by SCIP in the SCIPfree() call:
270  	 *       SCIP_CALL( SCIPcreate(&scip) );
271  	 *       ...
272  	 *       SCIP_CALL( SCIPincludeObjProp(scip, new MyProp(...), TRUE) );
273  	 *       ...
274  	 *       SCIP_CALL( SCIPfree(&scip) );  // destructor of MyProp is called here
275  	 */
276  	SCIP_EXPORT
277  	SCIP_RETCODE SCIPincludeObjProp(
278  	   SCIP*                 scip,               /**< SCIP data structure */
279  	   scip::ObjProp*        objprop,            /**< propagator object */
280  	   SCIP_Bool             deleteobject        /**< should the propagator object be deleted when propagator is freed? */
281  	   );
282  	
283  	/** returns the prop object of the given name, or 0 if not existing */
284  	SCIP_EXPORT
285  	scip::ObjProp* SCIPfindObjProp(
286  	   SCIP*                 scip,               /**< SCIP data structure */
287  	   const char*           name                /**< name of propagator */
288  	   );
289  	
290  	/** returns the prop object for the given propagator */
291  	SCIP_EXPORT
292  	scip::ObjProp* SCIPgetObjProp(
293  	   SCIP*                 scip,               /**< SCIP data structure */
294  	   SCIP_PROP*            prop                /**< propagator */
295  	   );
296  	
297  	#endif
298