1 /*===========================================================================*
2  * This file is part of the Branch, Constrain and Price Software (BiCePS)    *
3  *                                                                           *
4  * BiCePS is distributed under the Eclipse Public License as part of the     *
5  * COIN-OR repository (http://www.coin-or.org).                              *
6  *                                                                           *
7  * Authors:                                                                  *
8  *                                                                           *
9  *          Yan Xu, Lehigh University                                        *
10  *          Aykut Bulut, Lehigh University                                   *
11  *          Ted Ralphs, Lehigh University                                    *
12  *                                                                           *
13  * Conceptual Design:                                                        *
14  *                                                                           *
15  *          Yan Xu, Lehigh University                                        *
16  *          Ted Ralphs, Lehigh University                                    *
17  *          Laszlo Ladanyi, IBM T.J. Watson Research Center                  *
18  *          Matthew Saltzman, Clemson University                             *
19  *                                                                           *
20  * Copyright (C) 2001-2019, Lehigh University, Yan Xu, and Ted Ralphs.       *
21  * All Rights Reserved.                                                      *
22  *===========================================================================*/
23 
24 
25 //#############################################################################
26 // Borrow ideas from COIN/Cbc
27 //#############################################################################
28 
29 #ifndef BcpsBranchObject_h_
30 #define BcpsBranchObject_h_
31 
32 #include "BcpsModel.h"
33 
34 #include "Alps.h"
35 #include "AlpsEncoded.h"
36 
37 /*!
38 
39   # BcpsBranchObject
40 
41   BcpsBranchObject contains the member data required when branching a node.
42   Branching is creating new nodes from current one. This is an abstract class
43   that represents data needed for the branching process in the most general
44   form. Branching objects can be simple integer variables or more
45   complicated objects like SOS.
46 
47   Branching in general form is not necessarily binary. Branching process may
48   create more than two nodes.
49 
50   This interface lets creating arbitrary number of nodes. score() is updated
51   while the new branches are created. next() returns an integer that
52   identifies the new branch that will be created. This can be thought as
53   direction of the branch in the binary case. The indexing starts at 0. if
54   next() is 5, this indicates the branching object already created 5 nodes.
55 
56   BcpsBranchObject has no idea what next() returns or means. The super class
57   will put a meaning to it. For example, in a binary branching object
58   implementing this ABC, 0 might mean down node and 1 might mean up node.
59   When next() is 2, it means the branch object created both down and up nodes.
60 
61   score() is the quality of this object. It is used to compare this branching
62   object to others.
63 
64   # Notes(aykut):
65 
66   I removed up and down score data fields. I added a single field to store
67   the score. Up and down assumes binary branching and this is a general ABC.
68   Up and down should be implemented in the super class in case needed.
69 
70 */
71 
72 class BcpsBranchObject: virtual public AlpsKnowledge {
73   /// Type of branching. This will be set by the application built on top of
74   /// Bcps.
75   int type_;
76   /// Branch object index. The index is not necessarily the same as variable
77   /// index. It will be set by the user to identify this object.
78   int index_;
79   /// Quality/Goodness of this object. It is  used when comparing two branching
80   /// enities. Derived class can add more metrics like this.
81   double score_;
82   /// Current branching value. When branching on integer variables, it can be
83   /// the fractional value branched. Its meaning will be defined by the super
84   /// class.
85   double value_;
86 
87 public:
88   ///@name Constructors and Destructor.
89   //@{
90   /// Constructor.
91   BcpsBranchObject(int type, int index, int score);
92   /// Constructor.
93   BcpsBranchObject(int type, int index, double score, double value);
94   /// Copy constructor.
95   BcpsBranchObject(BcpsBranchObject const & other);
96   /// Copy assignment operator
97   BcpsBranchObject & operator=(BcpsBranchObject const & rhs);
98   /// Destructor.
~BcpsBranchObject()99   virtual ~BcpsBranchObject() { /* Do nothing */}
100   //@}
101 
102   ///@name Get functions.
103   //@{
104   /// Get type.
type()105   int type() const { return type_; }
106   /// Get index.
index()107   int index() const { return index_; }
108   /// Return score.
score()109   double score() const { return score_; }
110   /// Return object branching value.
value()111   double value() const { return value_; }
112   //@}
113 
114   ///@name Set functions.
115   //@{
116   /// Set score.
setScore(double score)117   void setScore(double score) { score_ = score; }
118   //@}
119 
120   ///@name Pure virtual functions.
121   /// The number of branch arms created for this branch object.
122   virtual int numBranches() const = 0;
123   /// The number of branch arms left to be evaluated.
124   virtual int numBranchesLeft() const = 0;
125   /// Spit out a branch and, update this or superclass fields if necessary.
126   virtual double branch(bool normalBranch = false) = 0;
127 
128   /// Encode the content of this into the given AlpsEncoded object.
129   virtual AlpsReturnStatus encode(AlpsEncoded * encoded) const;
130   /// Decode the given AlpsEncoded object into this.
131   virtual AlpsReturnStatus decodeToSelf(AlpsEncoded & encoded);
132   //@}
133 
134 private:
135   /// Disable default constructor.
136   BcpsBranchObject();
137 };
138 
139 #endif
140