Scippy

SCIP

Solving Constraint Integer Programs

objprobdata.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 objprobdata.h
17  * @brief C++ wrapper for user problem data
18  * @author Tobias Achterberg
19  */
20 
21 /*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
22 
23 #ifndef __SCIP_OBJPROBDATA_H__
24 #define __SCIP_OBJPROBDATA_H__
25 
26 
27 #include <cassert>
28 
29 #include "scip/scip.h"
30 #include "objscip/objcloneable.h"
31 
32 namespace scip
33 {
34 
35 /** @brief C++ wrapper for user problem data
36  *
37  * This class defines the interface for user problem data implemented in C++. This class can be accessed at any time
38  * using the methods SCIPgetObjProbData(). Therefore, it can be used to store data which has to be accessible within
39  * several plugins.
40  *
41  * - \ref type_prob.h "Corresponding C interface"
42  */
43 class ObjProbData
44 {
45 public:
46  /** default constructor */
47  ObjProbData()
48  {
49  }
50 
51  /** destructor */
52  virtual ~ObjProbData()
53  {
54  }
55 
56  /** destructor of user problem data to free original user data (called when original problem is freed)
57  *
58  * If the "deleteobject" flag in the SCIPcreateObjProb() method was set to TRUE, this method is not needed,
59  * because all the work to delete the user problem data can be done in the destructor of the user problem
60  * data object. If the "deleteobject" flag was set to FALSE, and the user problem data object stays alive
61  * after the SCIP problem is freed, this method should delete all the problem specific data that is no
62  * longer needed.
63  */
64  virtual SCIP_RETCODE scip_delorig(
65  SCIP* scip /**< SCIP data structure */
66  )
67  { /*lint --e{715}*/
68  return SCIP_OKAY;
69  }
70 
71  /** creates user data of transformed problem by transforming the original user problem data
72  * (called after problem was transformed)
73  *
74  * The user has two possibilities to implement this method:
75  * 1. Return the pointer to the original problem data object (this) as pointer to the transformed problem data
76  * object. The user may modify some internal attributes, but he has to make sure, that these modifications are
77  * reversed in the scip_deltrans() method, such that the original problem data is restored. In this case,
78  * he should set *deleteobject to FALSE, because the problem data must not be destructed by SCIP after the
79  * solving process is terminated.
80  * 2. Call the copy constructor of the problem data object and return the created copy as transformed problem
81  * data object. In this case, he probably wants to set *deleteobject to TRUE, thus letting SCIP call the
82  * destructor of the object if the transformed problem data is no longer needed.
83  */
84  virtual SCIP_RETCODE scip_trans(
85  SCIP* scip, /**< SCIP data structure */
86  ObjProbData** objprobdata, /**< pointer to store the transformed problem data object */
87  SCIP_Bool* deleteobject /**< pointer to store whether SCIP should delete the object after solving */
88  )
89  { /*lint --e{715}*/
90  assert(objprobdata != NULL);
91  assert(deleteobject != NULL);
92 
93  /* the default implementation just copies the pointer to the problem data object;
94  * SCIP must not destruct the transformed problem data object, because the original problem data must stay alive
95  */
96  *objprobdata = this;
97  *deleteobject = FALSE;
98 
99  return SCIP_OKAY;
100  }
101 
102  /** destructor of user problem data to free transformed user data (called when transformed problem is freed)
103  *
104  * If the "*deleteobject" flag in the scip_trans() method was set to TRUE, this method is not needed,
105  * because all the work to delete the user problem data can be done in the destructor of the user problem
106  * data object. If the "*deleteobject" flag was set to FALSE, and the user problem data object stays alive
107  * after the SCIP problem is freed, this method should delete all the problem specific data that is no
108  * longer needed.
109  */
110  virtual SCIP_RETCODE scip_deltrans(
111  SCIP* scip /**< SCIP data structure */
112  )
113  { /*lint --e{715}*/
114  return SCIP_OKAY;
115  }
116 
117  /** solving process initialization method of transformed data (called before the branch and bound process begins)
118  *
119  * This method is called before the branch and bound process begins and can be used to initialize user problem
120  * data that depends for example on the number of active problem variables, because these are now fixed.
121  */
122  virtual SCIP_RETCODE scip_initsol(
123  SCIP* scip /**< SCIP data structure */
124  )
125  { /*lint --e{715}*/
126  return SCIP_OKAY;
127  }
128 
129  /** solving process deinitialization method of transformed data (called before the branch and bound data is freed)
130  *
131  * This method is called before the branch and bound data is freed and should be used to free all data that
132  * was allocated in the solving process initialization method. The user has to make sure, that all LP rows associated
133  * to the transformed user problem data are released.
134  */
135  virtual SCIP_RETCODE scip_exitsol(
136  SCIP* scip, /**< SCIP data structure */
137  SCIP_Bool restart /**< was this exit solve call triggered by a restart? */
138  )
139  { /*lint --e{715}*/
140  return SCIP_OKAY;
141  }
142 
143  /** copies user data of source SCIP for the target SCIP
144  *
145  * This method should copy the problem data of the source SCIP and create a target problem data for (target)
146  * SCIP. Implementing this callback is optional. If the copying process was successful the target SCIP gets this
147  * problem data assigned. In case the result pointer is set to SCIP_DIDNOTRUN the target SCIP will have no problem data
148  * at all.
149  *
150  * The variable map and the constraint map can be used via the function SCIPgetVarCopy() and SCIPgetConsCopy(),
151  * respectively, to get for certain variables and constraints of the source SCIP the counter parts in the target
152  * SCIP. You should be very carefully in using these two methods since they could lead to an infinite loop due to
153  * recursion.
154  *
155  * possible return values for *result:
156  * - SCIP_DIDNOTRUN : the copying process was not performed
157  * - SCIP_SUCCESS : the copying process was successfully performed
158  */
159  virtual SCIP_RETCODE scip_copy(
160  SCIP* scip, /**< SCIP data structure */
161  SCIP* sourcescip, /**< source SCIP main data structure */
162  SCIP_HASHMAP* varmap, /**< a hashmap which stores the mapping of source variables to corresponding
163  * target variables */
164  SCIP_HASHMAP* consmap, /**< a hashmap which stores the mapping of source contraints to corresponding
165  * target constraints */
166  ObjProbData** objprobdata, /**< pointer to store the copied problem data object */
167  SCIP_Bool global, /**< create a global or a local copy? */
168  SCIP_RESULT* result /**< pointer to store the result of the call */
169  )
170  { /*lint --e{715}*/
171  (*objprobdata) = 0;
172  (*result) = SCIP_DIDNOTRUN;
173  return SCIP_OKAY;
174  }
175 };
176 
177 } /* namespace scip */
178 
179 
180 
181 /** creates empty problem, initializes all solving data structures, and sets the user problem data to point to the
182  * given user data object
183  *
184  * The method should be called in one of the following ways:
185  *
186  * 1. The user is resposible of deleting the object:
187  * SCIP_CALL( SCIPcreate(&scip) );
188  * ...
189  * MyProbData* myprobdata = new MyProbData(...);
190  * SCIP_CALL( SCIPcreateObjProb(scip, "probname", &myprobdata, FALSE) );
191  * ... // solve the problem
192  * SCIP_CALL( SCIPfreeProb(scip) );
193  * delete myprobdata; // delete probdata AFTER SCIPfreeProb() !
194  * ...
195  * SCIP_CALL( SCIPfree(&scip) );
196  *
197  * 2. The object pointer is passed to SCIP and deleted by SCIP in the SCIPfreeProb() call:
198  * SCIP_CALL( SCIPcreate(&scip) );
199  * ...
200  * SCIP_CALL( SCIPcreateObjProb(scip, "probname", new MyProbData(...), TRUE) );
201  * ...
202  * SCIP_CALL( SCIPfree(&scip) ); // problem is freed and destructor of MyProbData is called here
203  */
204 extern
205 SCIP_RETCODE SCIPcreateObjProb(
206  SCIP* scip, /**< SCIP data structure */
207  const char* name, /**< problem name */
208  scip::ObjProbData* objprobdata, /**< user problem data object */
209  SCIP_Bool deleteobject /**< should the user problem data object be deleted when problem is freed? */
210  );
211 
212 /** gets user problem data object
213  * Warning! This method should only be called after a problem was created with SCIPcreateObjProb().
214  * Otherwise, a segmentation fault may arise, or an undefined pointer is returned.
215  */
216 extern
217 scip::ObjProbData* SCIPgetObjProbData(
218  SCIP* scip /**< SCIP data structure */
219  );
220 
221 #endif
222