Merge pull request #14 from rlishtaba/feature/graph-algos

Feature/graph algos

Author: rlishtaba

README.md

@@ -10,7 +10,7 @@ Library of Algorithms, Data Structures, variety of solutions to common CS proble
 
 Add this line to your application as managed dependency:
 
-```python
+```bash
 py-algorithms>=0,<1
 ```
 
@@ -22,7 +22,7 @@ $ pip install py-algorithms
 
 ## What's inside?
 
-    ^ Data Structures
+### Data Structures
       - Deque
       - Stack (LIFO)
       - Queue (FIFO)
@@ -33,44 +33,59 @@ $ pip install py-algorithms
         - Min PQ
         - Max PQ
       - Suffix Array
+      
 ---
 
-    ^ Search
+### Search
       - Binary Search
+      
 ---
 
-    ^ Sort
+### Sort
       - Quick Sort
       - Shell Sort (Shell method)
       - Heap Sort (Fibonacci heap)
       - Merge Sort
       - Comb Sort
       - Bubble Sort
       - Selection Sort
+      
 ---
 
-    ^ String algorithms 
+### Graph Algorithms
+      - Depth-First-Search (DFS)
+      - Breadth-First-Search (BFS) 
+      - Topologial sort
+      - Floyd–Warshall algorithm
+      
+---
+
+### String Algorithms 
       - Patttern Matching
       - Boyer–Moore string search 
       - Knut-Morris-Prat string search 
----
+      
+---    
 
-    ^ Primality Tests
+### Primality Tests
       - Miller-Rabin primality test
       - Simple primality test
+      
 ---
-
-    ^ Algorithms
+    
+### Algorithms
       - Quick Union
       - Union Find
       - Weighted Union Find
       - Weighted Union Find with Path Compression
+      
 ---
 
-    ^ Challenges
+### Challenges
       - TopCoder (www.topcoder.com)
       - HackerRank problems & submissions (https://www.hackerrank.com)
       - CoderByte challenges (https://coderbyte.com)
+      
 ---
 
 ### Challenges
@@ -472,11 +487,44 @@ ds.is_sub_str('blah') #=> False
 
 ---
 
----
+### Graph Algorithms
 
-### String Algorithms
 
+#### Topological sort
+
+In the field of computer science, a topological sort or topological ordering of a directed graph is a 
+linear ordering of its vertices such that for every directed edge uv from vertex u to vertex v, u comes before v in the ordering.
+For instance, the vertices of the graph may represent tasks to be performed, and the edges may represent 
+constraints that one task must be performed before another; in this application, a topological ordering is just a valid sequence for the tasks. 
+A topological ordering is possible if and only if the graph has no directed cycles, that is, if it is a directed acyclic graph (DAG). 
+Any DAG has at least one topological ordering, and algorithms are known for constructing a topological ordering of any DAG in linear time.
 
+![topo-sort](http://www.stoimen.com/blog/wp-content/uploads/2012/10/2.-Topological-Sort.png)
+
+```python
+
+from py_algorithms.graph import new_directed_graph, topological_sort_f1
+
+
+dag = new_directed_graph()
+a = dag.insert_vertex('A')
+b = dag.insert_vertex('B')
+c = dag.insert_vertex('C')
+d = dag.insert_vertex('D')
+e = dag.insert_vertex('E')
+
+dag.insert_edge(a, e, None)
+dag.insert_edge(b, d, None)
+dag.insert_edge(c, d, None)
+dag.insert_edge(d, e, None)
+
+topological_sort_f1(dag) #=> [#<Vertex(C)>, #<Vertex(B)>, #<Vertex(D)>, #<Vertex(A)>, #<Vertex(E)>]
+
+```
+    
+---
+
+### String Algorithms
 
 ![boyer-moore-media](https://www.researchgate.net/profile/Monther_Aldwairi/publication/237067573/figure/fig1/AS:299315785420823@1448373852591/Figure-1-The-Boyer-Moore-algorithm-illustrated-while-checking-a-signature-in-Snort.png)
 

py_algorithms/graph/__init__.py

@@ -0,0 +1,28 @@
+__all__ = [
+    'Graph',
+    'Vertex',
+    'directed_graph'
+    'new_undirected_graph'
+    'new_topological_sort_f1'
+]
+
+from typing import List, Callable
+
+from .adt.graph import Graph
+from .adt.vertex import Vertex
+from .topological_sort import TopologicalSort
+
+
+def new_directed_graph() -> Graph:
+    return Graph(directed=True)
+
+
+def new_undirected_graph() -> Graph:
+    return Graph(directed=False)
+
+
+def new_topological_sort() -> Callable[[Graph], List[Vertex]]:
+    return TopologicalSort()
+
+
+topological_sort_f1 = new_topological_sort()

py_algorithms/graph/adt/__init__.py

@@ -0,0 +1,33 @@
+from typing import Any
+from typing import Tuple
+from typing import Union
+
+from .vertex import Vertex
+
+
+class Edge:
+    __slots__ = '_origin', '_destination', '_element'
+
+    def __init__(self, origin: Vertex, destination: Vertex, element: Any):
+        self._element = element
+        self._destination = destination
+        self._origin = origin
+
+    def endpoints(self) -> Tuple[Any, Any]:
+        return self._origin, self._destination
+
+    def opposite(self, v) -> Union[None, Vertex]:
+        return self._destination if v is self._origin else self._origin
+
+    def element(self) -> Any:
+        return self._element
+
+    def __hash__(self):
+        return hash((self._origin, self._destination,))
+
+    def __repr__(self):
+        return "#<{}({}) ({},{})>" \
+            .format(self.__class__.__name__,
+                    self.element(),
+                    self._origin.element(),
+                    self._destination.element())

py_algorithms/graph/adt/edge.py

@@ -0,0 +1,60 @@
+from typing import Any, Iterator
+from typing import List
+from typing import Set
+from typing import Union
+
+from .edge import Edge
+from .vertex import Vertex
+
+
+class Graph:
+    def __init__(self, directed: bool = False):
+        self._outgoing = {}
+        self._incoming = {} if directed else self._outgoing
+
+    def is_directed(self) -> bool:
+        return self._incoming is not self._outgoing
+
+    def vertex_count(self) -> int:
+        return len(self._outgoing)
+
+    def vertices(self) -> List[Vertex]:
+        return list(self._outgoing.keys())
+
+    def edge_count(self) -> int:
+        total = sum(len(self._outgoing[v]) for v in self._outgoing)
+        return total if self.is_directed() else total // 2
+
+    def edges(self) -> Set[Edge]:
+        result = set()
+        for sub_map in self._outgoing.values():
+            result.update(sub_map.values())
+        return result
+
+    def get_edge(self, u, v) -> Union[None, Edge]:
+        return self._outgoing[u].get(v)
+
+    def degree(self, v: Vertex, outgoing: bool = True) -> int:
+        adj = self._outgoing if outgoing else self._incoming
+        return len(adj[v])
+
+    def incident_edges(self,
+                       v: Vertex,
+                       outgoing: bool = True) -> Iterator[Edge]:
+        adj = self._outgoing if outgoing else self._incoming
+        for edge in adj[v].values():
+            yield edge
+
+    def insert_vertex(self, element: Any = None) -> Vertex:
+        v = Vertex(element)
+        self._outgoing[v] = {}
+        if self.is_directed():
+            self._incoming[v] = {}
+        return v
+
+    def insert_edge(self, origin: Vertex, destination: Vertex,
+                    element: Any) -> Edge:
+        e = Edge(origin, destination, element)
+        self._outgoing[origin][destination] = e
+        self._incoming[destination][origin] = e
+        return e

py_algorithms/graph/adt/graph.py

@@ -0,0 +1,18 @@
+from typing import Any
+
+
+class Vertex:
+    __slots__ = '_element'
+
+    def __init__(self, element: Any):
+        self._element = element
+
+    def element(self) -> Any:
+        return self._element
+
+    def __hash__(self) -> int:
+        return hash(id(self))
+
+    def __repr__(self):
+        return "#<{}({})>" \
+            .format(self.__class__.__name__, self.element())

py_algorithms/graph/adt/vertex.py

@@ -0,0 +1,32 @@
+from typing import List
+
+from .adt.graph import Graph
+
+from .adt.vertex import Vertex
+
+
+class TopologicalSort:
+    """
+    Representing topological sort for a given DAG ADT
+    """
+
+    def __call__(self, graph: Graph) -> List[Vertex]:
+        degrees = {}
+        queue = []
+        in_order = []
+
+        for u in graph.vertices():
+            degrees[u] = graph.degree(u, outgoing=False)
+            if degrees[u] == 0:
+                queue.append(u)
+
+        while len(queue) > 0:
+            u = queue.pop()
+            in_order.append(u)
+            for edge in graph.incident_edges(u):
+                v = edge.opposite(u)
+                degrees[v] -= 1
+                if degrees[v] == 0:
+                    queue.append(v)
+
+        return in_order

py_algorithms/graph/topological_sort.py

@@ -36,11 +36,17 @@
               'hackerrank challenges', 'boyer-moore',
               'boyer-moore-string-search', 'primality-tes',
               'miller-rabin', 'miller-rabin-primality-test',
-              'simple-primality-test'],
-    description="Library of Algorithms, Data Structures, variety of solutions to common "
+              'simple-primality-test', 'topological-sort', 'directed-graph',
+              'DAG', 'directed-acyclic-graph', 'simple-graph',
+              'undirected-graph', 'depth-first-search', 'DFS',
+              'breadth-first-search', 'BFS'],
+    description="Library of Algorithms, Data Structures, "
+                "variety of solutions to common "
                 "CS problems.",
-    long_description="Library of Algorithms, Data Structures, variety of solutions to common "
-                     "CS problems. Algorithms and Data Structures implemented using pure awesome "
+    long_description="Library of Algorithms, Data Structures, "
+                     "variety of solutions to common "
+                     "CS problems. Algorithms and Data Structures "
+                     "implemented using pure awesome "
                      "Python.",
     license="MIT",
     url='https://github.com/rlishtaba/py-algorithms',