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   scip_pricer.h
26   	 * @ingroup PUBLICCOREAPI
27   	 * @brief  public methods for variable pricer plugins
28   	 * @author Tobias Achterberg
29   	 * @author Timo Berthold
30   	 * @author Thorsten Koch
31   	 * @author Alexander Martin
32   	 * @author Marc Pfetsch
33   	 * @author Kati Wolter
34   	 * @author Gregor Hendel
35   	 * @author Leona Gottwald
36   	 */
37   	
38   	/*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
39   	
40   	#ifndef __SCIP_SCIP_PRICER_H__
41   	#define __SCIP_SCIP_PRICER_H__
42   	
43   	
44   	#include "scip/def.h"
45   	#include "scip/type_pricer.h"
46   	#include "scip/type_result.h"
47   	#include "scip/type_retcode.h"
48   	#include "scip/type_scip.h"
49   	
50   	#ifdef __cplusplus
51   	extern "C" {
52   	#endif
53   	
54   	/**@addtogroup PublicPricerMethods
55   	 *
56   	 * @{
57   	 */
58   	
59   	/** creates a variable pricer and includes it in SCIP
60   	 *  To use the variable pricer for solving a problem, it first has to be activated with a call to SCIPactivatePricer().
61   	 *  This should be done during the problem creation stage.
62   	 *
63   	 *  @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
64   	 *          SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
65   	 *
66   	 *  @pre This method can be called if SCIP is in one of the following stages:
67   	 *       - \ref SCIP_STAGE_INIT
68   	 *       - \ref SCIP_STAGE_PROBLEM
69   	 *
70   	 *  @note method has all pricer callbacks as arguments and is thus changed every time a new callback is added
71   	 *        in future releases; consider using SCIPincludePricerBasic() and setter functions
72   	 *        if you seek for a method which is less likely to change in future releases
73   	 */
74   	SCIP_EXPORT
75   	SCIP_RETCODE SCIPincludePricer(
76   	   SCIP*                 scip,               /**< SCIP data structure */
77   	   const char*           name,               /**< name of variable pricer */
78   	   const char*           desc,               /**< description of variable pricer */
79   	   int                   priority,           /**< priority of the variable pricer */
80   	   SCIP_Bool             delay,              /**< should the pricer be delayed until no other pricers or already existing
81   	                                              *   problem variables with negative reduced costs are found?
82   	                                              *   if this is set to FALSE it may happen that the pricer produces columns
83   	                                              *   that already exist in the problem (which are also priced in by the
84   	                                              *   default problem variable pricing in the same round) */
85   	   SCIP_DECL_PRICERCOPY  ((*pricercopy)),    /**< copy method of variable pricer or NULL if you don't want to copy your plugin into sub-SCIPs */
86   	   SCIP_DECL_PRICERFREE  ((*pricerfree)),    /**< destructor of variable pricer */
87   	   SCIP_DECL_PRICERINIT  ((*pricerinit)),    /**< initialize variable pricer */
88   	   SCIP_DECL_PRICEREXIT  ((*pricerexit)),    /**< deinitialize variable pricer */
89   	   SCIP_DECL_PRICERINITSOL((*pricerinitsol)),/**< solving process initialization method of variable pricer */
90   	   SCIP_DECL_PRICEREXITSOL((*pricerexitsol)),/**< solving process deinitialization method of variable pricer */
91   	   SCIP_DECL_PRICERREDCOST((*pricerredcost)),/**< reduced cost pricing method of variable pricer for feasible LPs */
92   	   SCIP_DECL_PRICERFARKAS((*pricerfarkas)),  /**< Farkas pricing method of variable pricer for infeasible LPs */
93   	   SCIP_PRICERDATA*      pricerdata          /**< variable pricer data */
94   	   );
95   	
96   	/** creates a variable pricer and includes it in SCIP with all non-fundamental callbacks set to NULL;
97   	 *  if needed, these can be added afterwards via setter functions SCIPsetPricerCopy(), SCIPsetPricerFree(),
98   	 *  SCIPsetPricerInity(), SCIPsetPricerExit(), SCIPsetPricerInitsol(), SCIPsetPricerExitsol(),
99   	 *  SCIPsetPricerFarkas();
100  	 *
101  	 *  To use the variable pricer for solving a problem, it first has to be activated with a call to SCIPactivatePricer().
102  	 *  This should be done during the problem creation stage.
103  	 *
104  	 *  @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
105  	 *          SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
106  	 *
107  	 *  @pre This method can be called if SCIP is in one of the following stages:
108  	 *       - \ref SCIP_STAGE_INIT
109  	 *       - \ref SCIP_STAGE_PROBLEM
110  	 *
111  	 *  @note if you want to set all callbacks with a single method call, consider using SCIPincludePricer() instead
112  	 */
113  	SCIP_EXPORT
114  	SCIP_RETCODE SCIPincludePricerBasic(
115  	   SCIP*                 scip,               /**< SCIP data structure */
116  	   SCIP_PRICER**         pricerptr,          /**< reference to a pricer, or NULL */
117  	   const char*           name,               /**< name of variable pricer */
118  	   const char*           desc,               /**< description of variable pricer */
119  	   int                   priority,           /**< priority of the variable pricer */
120  	   SCIP_Bool             delay,              /**< should the pricer be delayed until no other pricers or already existing
121  	                                              *   problem variables with negative reduced costs are found?
122  	                                              *   if this is set to FALSE it may happen that the pricer produces columns
123  	                                              *   that already exist in the problem (which are also priced in by the
124  	                                              *   default problem variable pricing in the same round) */
125  	   SCIP_DECL_PRICERREDCOST((*pricerredcost)),/**< reduced cost pricing method of variable pricer for feasible LPs */
126  	   SCIP_DECL_PRICERFARKAS((*pricerfarkas)),  /**< Farkas pricing method of variable pricer for infeasible LPs */
127  	   SCIP_PRICERDATA*      pricerdata          /**< variable pricer data */
128  	   );
129  	
130  	/** sets copy method of pricer
131  	 *
132  	 *  @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
133  	 *          SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
134  	 *
135  	 *  @pre This method can be called if SCIP is in one of the following stages:
136  	 *       - \ref SCIP_STAGE_INIT
137  	 *       - \ref SCIP_STAGE_PROBLEM
138  	 */
139  	SCIP_EXPORT
140  	SCIP_RETCODE SCIPsetPricerCopy(
141  	   SCIP*                 scip,               /**< SCIP data structure */
142  	   SCIP_PRICER*          pricer,             /**< pricer */
143  	   SCIP_DECL_PRICERCOPY ((*pricercopy))     /**< copy method of pricer or NULL if you don't want to copy your plugin into sub-SCIPs */
144  	   );
145  	
146  	/** sets destructor method of pricer
147  	 *
148  	 *  @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
149  	 *          SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
150  	 *
151  	 *  @pre This method can be called if SCIP is in one of the following stages:
152  	 *       - \ref SCIP_STAGE_INIT
153  	 *       - \ref SCIP_STAGE_PROBLEM
154  	 */
155  	SCIP_EXPORT
156  	SCIP_RETCODE SCIPsetPricerFree(
157  	   SCIP*                 scip,               /**< SCIP data structure */
158  	   SCIP_PRICER*          pricer,             /**< pricer */
159  	   SCIP_DECL_PRICERFREE ((*pricerfree))      /**< destructor of pricer */
160  	   );
161  	
162  	/** sets initialization method of pricer
163  	 *
164  	 *  @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
165  	 *          SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
166  	 *
167  	 *  @pre This method can be called if SCIP is in one of the following stages:
168  	 *       - \ref SCIP_STAGE_INIT
169  	 *       - \ref SCIP_STAGE_PROBLEM
170  	 */
171  	SCIP_EXPORT
172  	SCIP_RETCODE SCIPsetPricerInit(
173  	   SCIP*                 scip,               /**< SCIP data structure */
174  	   SCIP_PRICER*          pricer,             /**< pricer */
175  	   SCIP_DECL_PRICERINIT  ((*pricerinit))     /**< initialize pricer */
176  	   );
177  	
178  	/** sets deinitialization method of pricer
179  	 *
180  	 *  @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
181  	 *          SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
182  	 *
183  	 *  @pre This method can be called if SCIP is in one of the following stages:
184  	 *       - \ref SCIP_STAGE_INIT
185  	 *       - \ref SCIP_STAGE_PROBLEM
186  	 */
187  	SCIP_EXPORT
188  	SCIP_RETCODE SCIPsetPricerExit(
189  	   SCIP*                 scip,               /**< SCIP data structure */
190  	   SCIP_PRICER*          pricer,             /**< pricer */
191  	   SCIP_DECL_PRICEREXIT  ((*pricerexit))     /**< deinitialize pricer */
192  	   );
193  	
194  	/** sets solving process initialization method of pricer
195  	 *
196  	 *  @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
197  	 *          SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
198  	 *
199  	 *  @pre This method can be called if SCIP is in one of the following stages:
200  	 *       - \ref SCIP_STAGE_INIT
201  	 *       - \ref SCIP_STAGE_PROBLEM
202  	 */
203  	SCIP_EXPORT
204  	SCIP_RETCODE SCIPsetPricerInitsol(
205  	   SCIP*                 scip,               /**< SCIP data structure */
206  	   SCIP_PRICER*          pricer,             /**< pricer */
207  	   SCIP_DECL_PRICERINITSOL ((*pricerinitsol))/**< solving process initialization method of pricer */
208  	   );
209  	
210  	/** sets solving process deinitialization method of pricer
211  	 *
212  	 *  @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
213  	 *          SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
214  	 *
215  	 *  @pre This method can be called if SCIP is in one of the following stages:
216  	 *       - \ref SCIP_STAGE_INIT
217  	 *       - \ref SCIP_STAGE_PROBLEM
218  	 */
219  	SCIP_EXPORT
220  	SCIP_RETCODE SCIPsetPricerExitsol(
221  	   SCIP*                 scip,               /**< SCIP data structure */
222  	   SCIP_PRICER*          pricer,             /**< pricer */
223  	   SCIP_DECL_PRICEREXITSOL((*pricerexitsol)) /**< solving process deinitialization method of pricer */
224  	   );
225  	
226  	/** returns the variable pricer of the given name, or NULL if not existing */
227  	SCIP_EXPORT
228  	SCIP_PRICER* SCIPfindPricer(
229  	   SCIP*                 scip,               /**< SCIP data structure */
230  	   const char*           name                /**< name of variable pricer */
231  	   );
232  	
233  	/** returns the array of currently available variable pricers; active pricers are in the first slots of the array */
234  	SCIP_EXPORT
235  	SCIP_PRICER** SCIPgetPricers(
236  	   SCIP*                 scip                /**< SCIP data structure */
237  	   );
238  	
239  	/** returns the number of currently available variable pricers */
240  	SCIP_EXPORT
241  	int SCIPgetNPricers(
242  	   SCIP*                 scip                /**< SCIP data structure */
243  	   );
244  	
245  	/** returns the number of currently active variable pricers, that are used in the LP solving loop */
246  	SCIP_EXPORT
247  	int SCIPgetNActivePricers(
248  	   SCIP*                 scip                /**< SCIP data structure */
249  	   );
250  	
251  	/** sets the priority of a variable pricer */
252  	SCIP_EXPORT
253  	SCIP_RETCODE SCIPsetPricerPriority(
254  	   SCIP*                 scip,               /**< SCIP data structure */
255  	   SCIP_PRICER*          pricer,             /**< variable pricer */
256  	   int                   priority            /**< new priority of the variable pricer */
257  	   );
258  	
259  	/** activates pricer to be used for the current problem
260  	 *  This method should be called during the problem creation stage for all pricers that are necessary to solve
261  	 *  the problem model.
262  	 *  The pricers are automatically deactivated when the problem is freed.
263  	 *
264  	 *  @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
265  	 *          SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
266  	 *
267  	 *  @pre This method can be called if SCIP is in one of the following stages:
268  	 *       - \ref SCIP_STAGE_PROBLEM
269  	 */
270  	SCIP_EXPORT
271  	SCIP_RETCODE SCIPactivatePricer(
272  	   SCIP*                 scip,               /**< SCIP data structure */
273  	   SCIP_PRICER*          pricer              /**< variable pricer */
274  	   );
275  	
276  	/** deactivates pricer
277  	 *
278  	 *  @return \ref SCIP_OKAY is returned if everything worked. Otherwise a suitable error code is passed. See \ref
279  	 *          SCIP_Retcode "SCIP_RETCODE" for a complete list of error codes.
280  	 *
281  	 *  @pre This method can be called if SCIP is in one of the following stages:
282  	 *       - \ref SCIP_STAGE_PROBLEM
283  	 *       - \ref SCIP_STAGE_EXITSOLVE
284  	 */
285  	SCIP_EXPORT
286  	SCIP_RETCODE SCIPdeactivatePricer(
287  	   SCIP*                 scip,               /**< SCIP data structure */
288  	   SCIP_PRICER*          pricer              /**< variable pricer */
289  	   );
290  	
291  	/** @} */
292  	
293  	#ifdef __cplusplus
294  	}
295  	#endif
296  	
297  	#endif
298