[WIP] Added Binomial Heap (#68)

* added BinomialTreeNode

* added BinomialTree

* added BinomialHeap

Author: czgdp1807

pydatastructs/miscellaneous_data_structures/__init__.py

@@ -2,8 +2,14 @@
 
 from . import (
     stack,
+    binomial_trees
 )
 
+from .binomial_trees import (
+    BinomialTree
+)
+__all__.extend(binomial_trees.__all__)
+
 from .stack import (
     Stack,
 )

pydatastructs/miscellaneous_data_structures/binomial_trees.py

@@ -0,0 +1,79 @@
+from pydatastructs.utils.misc_util import BinomialTreeNode, _check_type
+
+__all__ = [
+    'BinomialTree'
+]
+
+class BinomialTree(object):
+    """
+    Represents binomial trees
+
+    Parameters
+    ==========
+
+    root: BinomialTreeNode
+        The root of the binomial tree.
+        By default, None
+    order: int
+        The order of the binomial tree.
+        By default, None
+
+    Examples
+    ========
+
+    >>> from pydatastructs import BinomialTree, BinomialTreeNode
+    >>> root = BinomialTreeNode(1, 1)
+    >>> tree = BinomialTree(root, 0)
+    >>> tree.is_empty
+    False
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Binomial_heap
+    """
+    __slots__ = ['root', 'order']
+
+    def __new__(cls, root=None, order=None):
+        if root is not None and \
+            not _check_type(root, BinomialTreeNode):
+            raise TypeError("%s i.e., root should be of "
+                             "type BinomialTreeNode."%(root))
+        if order is not None and not _check_type(order, int):
+            raise TypeError("%s i.e., order should be of "
+                             "type int."%(order))
+        obj = object.__new__(cls)
+        if root is not None:
+            root.is_root = True
+        obj.root = root
+        obj.order = order
+        return obj
+
+    def add_sub_tree(self, other_tree):
+        """
+        Adds a sub tree to current tree.
+
+        Parameters
+        ==========
+
+        other_tree: BinomialTree
+
+        Raises
+        ======
+
+        ValueError: If order of the two trees
+                    are different.
+        """
+        if not _check_type(other_tree, BinomialTree):
+            raise TypeError("%s i.e., other_tree should be of "
+                             "type BinomialTree"%(other_tree))
+        if self.order != other_tree.order:
+            raise ValueError("Orders of both the trees should be same.")
+        self.root.children.append(other_tree.root)
+        other_tree.root.parent = self.root
+        other_tree.root.is_root = False
+        self.order += 1
+
+    @property
+    def is_empty(self):
+        return self.root is None

pydatastructs/miscellaneous_data_structures/tests/test_binomial_trees.py

@@ -0,0 +1,17 @@
+from pydatastructs.miscellaneous_data_structures.binomial_trees import BinomialTree
+from pydatastructs.utils.raises_util import raises
+from pydatastructs.utils.misc_util import BinomialTreeNode
+
+# only tests the corner cases
+def test_BinomialTree():
+    assert raises(TypeError, lambda: BinomialTree(1, 1))
+    assert raises(TypeError, lambda: BinomialTree(None, 1.5))
+
+    bt = BinomialTree()
+    assert raises(TypeError, lambda: bt.add_sub_tree(None))
+    bt1 = BinomialTree(BinomialTreeNode(1, 1), 0)
+    node = BinomialTreeNode(2, 2)
+    node.add_children(BinomialTreeNode(3, 3))
+    bt2 = BinomialTree(node, 1)
+    assert raises(ValueError, lambda: bt1.add_sub_tree(bt2))
+    assert bt1.is_empty is False

pydatastructs/trees/__init__.py

@@ -16,6 +16,7 @@
 __all__.extend(space_partitioning_trees.__all__)
 
 from .heaps import (
-    BinaryHeap
+    BinaryHeap,
+    BinomialHeap
 )
 __all__.extend(heaps.__all__)

pydatastructs/trees/heaps.py

@@ -1,11 +1,14 @@
-from pydatastructs.utils.misc_util import _check_type, NoneType, TreeNode
-from pydatastructs.linear_data_structures.arrays import ArrayForTrees
+from pydatastructs.utils.misc_util import _check_type, NoneType, TreeNode, BinomialTreeNode
+from pydatastructs.linear_data_structures.arrays import (ArrayForTrees,
+     DynamicOneDimensionalArray)
+from pydatastructs.miscellaneous_data_structures.binomial_trees import BinomialTree
 
 __all__ = [
-    'BinaryHeap'
+    'BinaryHeap',
+    'BinomialHeap'
 ]
 
-class Heap:
+class Heap(object):
     """
     Abstract class for representing heaps.
     """
@@ -181,3 +184,217 @@ def __str__(self):
                                 node.key, node.data,
                                 node.right if node.right <= self._last_pos_filled else None)
         return str(to_be_printed)
+
+
+class BinomialHeap(Heap):
+    """
+    Represents binomial heap.
+
+    Parameters
+    ==========
+
+    root_list: list/tuple
+        By default, []
+        The list of BinomialTree object references
+        in sorted order.
+
+    Examples
+    ========
+
+    >>> from pydatastructs import BinomialHeap
+    >>> b = BinomialHeap()
+    >>> b.insert(1, 1)
+    >>> b.insert(2, 2)
+    >>> b.find_minimum().key
+    1
+    >>> b.find_minimum().children[0].key
+    2
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Binomial_heap
+    """
+    __slots__ = ['root_list']
+
+    def __new__(cls, root_list=[]):
+        if not all((_check_type(root, BinomialTree))
+                for root in root_list):
+                    raise TypeError("The root_list should contain "
+                                    "references to objects of BinomialTree.")
+        obj = Heap.__new__(cls)
+        obj.root_list = DynamicOneDimensionalArray(BinomialTree, root_list)
+        return obj
+
+    def merge_tree(self, tree1, tree2):
+        """
+        Merges two BinomialTree objects.
+
+        Parameters
+        ==========
+
+        tree1: BinomialTree
+
+        tree2: BinomialTree
+        """
+        if (not _check_type(tree1, BinomialTree)) or \
+            (not _check_type(tree2, BinomialTree)):
+            raise TypeError("Both the trees should be of type "
+                            "BinomalTree.")
+        ret_value = None
+        if tree1.root.key <= tree2.root.key:
+            tree1.add_sub_tree(tree2)
+            ret_value = tree1
+        else:
+            tree2.add_sub_tree(tree1)
+            ret_value = tree2
+        return ret_value
+
+    def _merge_heap_last_new_tree(self, new_root_list, new_tree):
+        """
+        Merges last tree node in root list with the incoming tree.
+        """
+        pos = new_root_list._last_pos_filled
+        if (new_root_list.size != 0) and new_root_list[pos].order == new_tree.order:
+            new_root_list[pos] = self.merge_tree(new_root_list[pos], new_tree)
+        else:
+            new_root_list.append(new_tree)
+
+    def merge(self, other_heap):
+        """
+        Merges current binomial heap with the given binomial heap.
+
+        Parameters
+        ==========
+
+        other_heap: BinomialHeap
+        """
+        if not _check_type(other_heap, BinomialHeap):
+            raise TypeError("Other heap is not of type BinomialHeap.")
+        new_root_list = DynamicOneDimensionalArray(BinomialTree, 0)
+        i, j = 0, 0
+        while ((i <= self.root_list._last_pos_filled) and
+               (j <= other_heap.root_list._last_pos_filled)):
+            new_tree = None
+            while self.root_list[i] is None:
+                i += 1
+            while other_heap.root_list[j] is None:
+                j += 1
+            if self.root_list[i].order == other_heap.root_list[j].order:
+                new_tree = self.merge_tree(self.root_list[i],
+                                           other_heap.root_list[j])
+                i += 1
+                j += 1
+            else:
+                if self.root_list[i].order < other_heap.root_list[j].order:
+                    new_tree = self.root_list[i]
+                    i += 1
+                else:
+                    new_tree = other_heap.root_list[j]
+                    j += 1
+            self._merge_heap_last_new_tree(new_root_list, new_tree)
+
+        while i <= self.root_list._last_pos_filled:
+            new_tree = self.root_list[i]
+            self._merge_heap_last_new_tree(new_root_list, new_tree)
+            i += 1
+        while j <= other_heap.root_list._last_pos_filled:
+            new_tree = other_heap.root_list[j]
+            self._merge_heap_last_new_tree(new_root_list, new_tree)
+            j += 1
+        self.root_list = new_root_list
+
+    def insert(self, key, data):
+        """
+        Inserts new node with the given key and data.
+
+        key
+            The key of the node which can be operated
+            upon by relational operators.
+
+        data
+            The data to be stored in the new node.
+        """
+        new_node = BinomialTreeNode(key, data)
+        new_tree = BinomialTree(root=new_node, order=0)
+        new_heap = BinomialHeap(root_list=[new_tree])
+        self.merge(new_heap)
+
+    def find_minimum(self, **kwargs):
+        """
+        Finds the node with the minimum key.
+
+        Returns
+        =======
+
+        min_node: BinomialTreeNode
+        """
+        if self.is_empty:
+            raise ValueError("Binomial heap is empty.")
+        min_node = None
+        idx, min_idx = 0, None
+        for tree in self.root_list:
+            if ((min_node is None) or
+                (tree is not None and tree.root is not None and
+                 min_node.key > tree.root.key)):
+                min_node = tree.root
+                min_idx = idx
+            idx += 1
+        if kwargs.get('get_index', None) is not None:
+            return min_node, min_idx
+        return min_node
+
+    def delete_minimum(self):
+        """
+        Deletes the node with minimum key.
+        """
+        min_node, min_idx = self.find_minimum(get_index=True)
+        child_root_list = []
+        for k, child in enumerate(min_node.children):
+            if child is not None:
+                child_root_list.append(BinomialTree(root=child, order=k))
+        self.root_list.delete(min_idx)
+        child_heap = BinomialHeap(root_list=child_root_list)
+        self.merge(child_heap)
+
+    @property
+    def is_empty(self):
+        return self.root_list._last_pos_filled == -1
+
+    def decrease_key(self, node, new_key):
+        """
+        Decreases the key of the given node.
+
+        Parameters
+        ==========
+
+        node: BinomialTreeNode
+            The node whose key is to be reduced.
+        new_key
+            The new key of the given node,
+            should be less than the current key.
+        """
+        if node.key <= new_key:
+            raise ValueError("The new key "
+            "should be less than current node's key.")
+        node.key = new_key
+        while ((not node.is_root) and
+               (node.parent.key > node.key)):
+            node.parent.key, node.key = \
+                node.key, node.parent.key
+            node.parent.data, node.data = \
+                node.data, node.parent.data
+            node = node.parent
+
+    def delete(self, node):
+        """
+        Deletes the given node.
+
+        Parameters
+        ==========
+
+        node: BinomialTreeNode
+            The node which is to be deleted.
+        """
+        self.decrease_key(node, self.find_minimum().key - 1)
+        self.delete_minimum()

pydatastructs/trees/tests/test_heaps.py

@@ -1,6 +1,8 @@
-from pydatastructs.trees.heaps import BinaryHeap
-from pydatastructs.utils.misc_util import TreeNode
+from pydatastructs.trees.heaps import BinaryHeap, BinomialHeap
+from pydatastructs.miscellaneous_data_structures.binomial_trees import BinomialTree
+from pydatastructs.utils.misc_util import TreeNode, BinomialTreeNode
 from pydatastructs.utils.raises_util import raises
+from collections import deque as Queue
 
 def test_BinaryHeap():
 
@@ -44,3 +46,94 @@ def test_BinaryHeap():
     expected_sorted_elements = [2, 3, 7, 17, 19, 25, 36, 100]
     sorted_elements = [min_heap.extract().key for _ in range(8)]
     assert expected_sorted_elements == sorted_elements
+
+def test_BinomialHeap():
+
+    # Corner cases
+    assert raises(TypeError, lambda:
+                  BinomialHeap(
+                    root_list=[BinomialTreeNode(1, 1), None])
+                  ) is True
+    tree1 = BinomialTree(BinomialTreeNode(1, 1), 0)
+    tree2 = BinomialTree(BinomialTreeNode(2, 2), 0)
+    bh = BinomialHeap(root_list=[tree1, tree2])
+    assert raises(TypeError, lambda:
+                  bh.merge_tree(BinomialTreeNode(2, 2), None))
+    assert raises(TypeError, lambda:
+                  bh.merge(None))
+
+    # Testing BinomialHeap.merge
+    nodes = [BinomialTreeNode(1, 1), # 0
+            BinomialTreeNode(3, 3), # 1
+            BinomialTreeNode(9, 9), # 2
+            BinomialTreeNode(11, 11), # 3
+            BinomialTreeNode(6, 6), # 4
+            BinomialTreeNode(14, 14), # 5
+            BinomialTreeNode(2, 2), # 6
+            BinomialTreeNode(7, 7), # 7
+            BinomialTreeNode(4, 4), # 8
+            BinomialTreeNode(8, 8), # 9
+            BinomialTreeNode(12, 12), # 10
+            BinomialTreeNode(10, 10), # 11
+            BinomialTreeNode(5, 5), # 12
+            BinomialTreeNode(21, 21)] # 13
+
+    nodes[2].add_children(nodes[3])
+    nodes[4].add_children(nodes[5])
+    nodes[6].add_children(nodes[9], nodes[8], nodes[7])
+    nodes[7].add_children(nodes[11], nodes[10])
+    nodes[8].add_children(nodes[12])
+    nodes[10].add_children(nodes[13])
+
+    tree11 = BinomialTree(nodes[0], 0)
+    tree12 = BinomialTree(nodes[2], 1)
+    tree13 = BinomialTree(nodes[6], 3)
+    tree21 = BinomialTree(nodes[1], 0)
+
+    heap1 = BinomialHeap(root_list=[tree11, tree12, tree13])
+    heap2 = BinomialHeap(root_list=[tree21])
+
+    def bfs(heap):
+        bfs_trav = []
+        for i in range(heap.root_list._last_pos_filled + 1):
+            layer = []
+            bfs_q = Queue()
+            bfs_q.append(heap.root_list[i].root)
+            while len(bfs_q) != 0:
+                curr_node = bfs_q.popleft()
+                if curr_node is not None:
+                    layer.append(curr_node.key)
+                    for _i in range(curr_node.children._last_pos_filled + 1):
+                        bfs_q.append(curr_node.children[_i])
+            if layer != []:
+                bfs_trav.append(layer)
+        return bfs_trav
+
+    heap1.merge(heap2)
+    expected_bfs_trav = [[1, 3, 9, 11], [2, 8, 4, 7, 5, 10, 12, 21]]
+    assert bfs(heap1) == expected_bfs_trav
+
+    # Testing Binomial.find_minimum
+    assert heap1.find_minimum().key == 1
+
+    # Testing Binomial.delete_minimum
+    heap1.delete_minimum()
+    assert bfs(heap1) == [[3], [9, 11], [2, 8, 4, 7, 5, 10, 12, 21]]
+    assert raises(ValueError, lambda: heap1.decrease_key(nodes[3], 15))
+    heap1.decrease_key(nodes[3], 0)
+    assert bfs(heap1) == [[3], [0, 9], [2, 8, 4, 7, 5, 10, 12, 21]]
+    heap1.delete(nodes[12])
+    assert bfs(heap1) == [[3, 8], [0, 9, 2, 7, 4, 10, 12, 21]]
+
+    # Testing BinomialHeap.insert
+    heap = BinomialHeap()
+    assert raises(ValueError, lambda: heap.find_minimum())
+    heap.insert(1, 1)
+    heap.insert(3, 3)
+    heap.insert(6, 6)
+    heap.insert(9, 9)
+    heap.insert(14, 14)
+    heap.insert(11, 11)
+    heap.insert(2, 2)
+    heap.insert(7, 7)
+    assert bfs(heap) == [[1, 3, 6, 2, 9, 7, 11, 14]]

pydatastructs/utils/__init__.py

@@ -3,6 +3,7 @@
 from . import misc_util
 from .misc_util import (
     TreeNode,
-    LinkedListNode
+    LinkedListNode,
+    BinomialTreeNode
 )
 __all__.extend(misc_util.__all__)

pydatastructs/utils/misc_util.py

@@ -1,14 +1,19 @@
-
-
 __all__ = [
     'TreeNode',
-    'LinkedListNode'
+    'LinkedListNode',
+    'BinomialTreeNode'
 ]
 
 _check_type = lambda a, t: isinstance(a, t)
 NoneType = type(None)
 
-class TreeNode(object):
+class Node(object):
+    """
+    Abstract class representing a node.
+    """
+    pass
+
+class TreeNode(Node):
     """
     Represents node in trees.
 
@@ -42,19 +47,70 @@ def __str__(self):
         """
         return str((self.left, self.key, self.data, self.right))
 
-class LinkedListNode(object):
+class BinomialTreeNode(TreeNode):
     """
-    Represents node in linked lists.
+    Represents node in binomial trees.
 
     Parameters
     ==========
 
     data
         Any valid data to be stored in the node.
+    key
+        Required for comparison operations.
+
+    Note
+    ====
+
+    The following are the data members of the class:
+
+    parent: BinomialTreeNode
+        A reference to the BinomialTreeNode object
+        which is a prent of this.
+    children: DynamicOneDimensionalArray
+        An array of references to BinomialTreeNode objects
+        which are children this node.
+    is_root: bool, by default, False
+        If the current node is a root of the tree then
+        set it to True otherwise False.
     """
+    __slots__ = ['parent', 'key', 'children', 'data', 'is_root']
 
-    # __slots__ = ['data']
+    def __new__(cls, key, data):
+        from pydatastructs.linear_data_structures.arrays import DynamicOneDimensionalArray
+        obj = object.__new__(cls)
+        obj.data, obj.key = data, key
+        obj.children, obj.parent, obj.is_root = (
+        DynamicOneDimensionalArray(BinomialTreeNode, 0),
+        None,
+        False
+        )
+        return obj
 
+    def add_children(self, *children):
+        """
+        Adds children of current node.
+        """
+        for child in children:
+            self.children.append(child)
+            child.parent = self
+
+    def __str__(self):
+        """
+        For printing the key and data.
+        """
+        return str((self.key, self.data))
+
+class LinkedListNode(Node):
+    """
+    Represents node in linked lists.
+
+    Parameters
+    ==========
+
+    data
+        Any valid data to be stored in the node.
+    """
     def __new__(cls, data=None, links=['next'], addrs=[None]):
         obj = object.__new__(cls)
         obj.data = data