changed implementation of kruskal algorithm to union-find data structure to decrease time complexity. Write doc and adapt setup.py to pep8 style guide

Author: Michele De Vita

docs/Minumum spanning tree.rst

@@ -0,0 +1,25 @@
+=======================
+Minimum spanning tree
+=======================
+
+
+Given a weighted connected graph (a graph with weights on the edges), the minimum spanning tree is a spanning tree that
+minimize the weights of the edges.
+
+
+==========================
+Features
+==========================
+
+* Algorithms implemented:
+    - Kruskal
+
+* To create the Minimum spanning tree use the *minimum_spanning_tree* function, it takes in input the list of weighted edges, that it is represented in python as a tuple composed by the edge, a tuple of two vertexes identified by numbers, and the weight, a number (e.g. ((2,5), 5))
+
+* Code example:
+
+.. code-block:: python
+
+    from pygorithm.minimum_spanning_tree import kruskal
+    edges_weighted = [((1,2), 4), ((2, 4), 5), ((1,3), 13), ((2, 3),  9), ((1, 4), 1)]
+    kruskal.minimum_spanning_tree(edges_weighted) #[((1, 4), 1), ((1, 2), 4), ((2, 3), 9)]

docs/index.rst

@@ -15,6 +15,7 @@ Table of Contents:
 
    Sorting
    Searching
+   Minimum spanning tree
 
 
 -----------------

pygorithm/minimun_spanning_tree/kruskal.py

@@ -1,51 +1,49 @@
-import copy
+"""
+Kruskal algorithm for minimum spanning tree in a weighted graph with union–find data structure
+"""
+__author__ = "Michele De Vita <[email protected]>"
+__date__ = "14/07/2017"
 
 
-def get_nodes(edges_weighted: list):
+def get_vertexes(edges_weighted: list):
     return set(sum((edge for edge, weight in edges_weighted), ()))
 
 
-def is_reversed(curr_edge, edge):
-    return curr_edge[0] == edge[1] and curr_edge[1] == edge[0]
+def set_of(vertex, forest):
+    for tree in forest:
+        if vertex in tree:
+            return tree
+    return None
 
 
-def has_cycle(edges_w):
-    edges_w += [((b, a), weight) for (a, b), weight in edges_w]
-    for edge, weight in edges_w:
-        if rec_cycle_detector(edge, edge, copy.deepcopy(edges_w), 1):
-            return True
-    return False
-
-
-def rec_cycle_detector(s_edge, curr_edge, edges_w, step=None):
-    if step > 2 and curr_edge[1] == s_edge[0]:
-        return True
-    neightbours = ((edge, weight) for edge, weight in edges_w if
-                   curr_edge[1] == edge[0] and not is_reversed(curr_edge, edge))
-    for neightbour in neightbours:
-        edges_w.remove(neightbour)
-        if rec_cycle_detector(s_edge, neightbour[0], edges_w, step + 1):
-            return True
-    return False
-
-
-def vertex_of(edge_w: tuple) -> set:
-    return set(edge_w[0])
+def union(u_set, v_set, forest):
+    forest.remove(u_set)
+    forest.remove(v_set)
+    forest.append(v_set + u_set)
+    return forest
 
 
 def minimum_spanning_tree(edges_weighted: list):
     """
-    :param edges_weighted: A list of pair with first element the edge as tuple (e.g. (1,4))
-                                          and the weight as second element
-    :return:
+    :param edges_weighted: A list of pair with first element the edge as tuple
+                                          and the weight as second element (e.g. ((1,4), 5) )
+    :return: the list of edges explored
     """
     edges_weighted.sort(key=lambda pair: pair[1])
-    edges_list = []
-    e_vertexes = set()
-    vertexes = get_nodes(edges_weighted)
-    while vertexes != e_vertexes:
-        edge_w = edges_weighted.pop(0)
-        if (len(edges_list) > 2 and not has_cycle(edges_list + [edge_w])) or len(edges_list) <= 2:
-            e_vertexes.update(vertex_of(edge_w))
-            edges_list.append(edge_w)
-    return edges_list
+    edges_explored = []
+    forest = [[v] for v in get_vertexes(edges_weighted)]
+    for (u, v), weight in edges_weighted:
+        u_set, v_set = set_of(u, forest), set_of(v, forest)
+        if u_set != v_set:
+            forest = union(u_set, v_set, forest)
+            edges_explored.append(((u, v), weight))
+    return edges_explored
+
+
+def time_complexities():
+    return '''Worst case: O(E log(V)) where E in the number of edges and V the number of vertexes'''
+
+
+def get_code():
+    import inspect
+    return inspect.getsource(minimum_spanning_tree)

setup.py

@@ -10,19 +10,19 @@
     long_description = f.read()
 
 setup(
-    name = 'pygorithm',
-    version = '0.1.dev2',
-    description = 'A Python algorithms module for learning',
-    long_description = long_description,
+    name='pygorithm',
+    version='0.1.dev2',
+    description='A Python algorithms module for learning',
+    long_description=long_description,
     # The project's main homepage.
     url='https://github.com/OmkarPathak/pygorithms',
     # Author details
-    author = 'Omkar Pathak',
-    author_email = '[email protected]',
+    author='Omkar Pathak',
+    author_email='[email protected]',
     # Choose your license
-    license = 'MIT',
+    license='MIT',
     # See https://pypi.python.org/pypi?%3Aaction=list_classifiers
-    classifiers = [
+    classifiers=[
         # Indicate who your project is intended for
         'Intended Audience :: Developers',
         'Topic :: Software Development :: Libraries',
@@ -38,5 +38,5 @@
         'Programming Language :: Python :: 3.4',
         'Programming Language :: Python :: 3.5',
     ],
-    packages = find_packages()
+    packages=find_packages()
 )

tests/kruskal_mst_tests.py

@@ -0,0 +1,24 @@
+import unittest
+
+from pygorithm.minimun_spanning_tree import kruskal
+
+
+class KruskalTest(unittest.TestCase):
+
+    def test_minimum_spanning_tree(self):
+        """
+        test inspired from the example at the following link: https://en.wikipedia.org/wiki/Kruskal%27s_algorithm
+        """
+        edges_weighted = [((1, 2), 7), ((2, 3), 8), ((1, 4), 5), ((2, 4), 9),
+                         ((2, 5), 7), ((3, 5), 5), ((4, 6), 6), ((5, 6), 8),
+                         ((5, 7), 9), ((6, 7), 11), ((4, 5), 15)]
+        expected = [((1, 4), 5), ((3, 5), 5), ((4, 6), 6), ((1, 2), 7), ((2, 5), 7), ((5, 7), 9)]
+        self.assertEqual(kruskal.minimum_spanning_tree(edges_weighted), expected)
+
+    def test_minimum_spanning_tree_2(self):
+        """
+        Test inspired by the gif at the left of the page https://en.wikipedia.org/wiki/Kruskal%27s_algorithm
+        """
+        edges_weighted = [((1,2), 3), ((1, 5), 1), ((2, 5), 4), ((2, 3), 5), ((3, 5), 6), ((3, 4), 2), ((4, 5), 7)]
+        expected = [((1, 5), 1), ((3, 4), 2), ((1, 2), 3), ((2, 3), 5)]
+        self.assertEqual(kruskal.minimum_spanning_tree(edges_weighted), expected)