Add dijkstra pathfinding algorithm

This adds one test and documentation regarding dijkstras pathfinding
algorithm. I'm not sure exactly how the documentation is generated,
but this adheres pretty strictly to the pattern set in the other
documentation so it should work.

This adds weighted undirected graphs to data structures as well, which
is a good standard implementation for testing the pathfinding algorithms.

* CONTRIBUTORS.md - Add myself
* docs/Data_Structure.rst - Add
+ docs/Pathing.rst - Add documentation for the new pathing/ submodule
* docs/index.rst - Add Pathing to the index
* pygorithm/__init__.py - Add myself to the contributors
* pygorithm/data_structures.py - Add WeightedUndirectedGraph and very minor
indentation changes
+ pygorithm/pathing/__init__.py - In the same format as the others
+ pygorithm/pathing/dijkstra.py - The simplest of pathfinding algorithms
* tests/test_data_structure.py - Add tests for the new graph type
+ tests/test_pathing.py - Test the example shown in the documentation

Author: Tjstretchalot

CONTIRBUTORS.md

@@ -12,4 +12,5 @@
  - [dstark85](https://github.com/dstark85)
  - Songzhuozhuo '[souo](https://github.com/souo)'
  - Emil '[Skeen](https://github.com/Skeen)' Madsen
- - Ian '[IanDoarn](https://github.com/IanDoarn)' Doarn
+ - Ian '[IanDoarn](https://github.com/IanDoarn)' Doarn
+ - Timothy '[Tjstretchalot](https://github.com/Tjstretchalot)' Moore

docs/Data_Structure.rst

@@ -172,6 +172,12 @@ Graph
     .. autoclass:: WeightedGraph
        :members:
 
+ 
+    Weighted Undirected Graph
+    -------------------------
+    .. autoclass:: WeightedUndirectedGraph
+       :members:
+
 
     Topological Sort
     ----------------
@@ -190,6 +196,7 @@ Graph
     .. autoclass:: CheckCycleUndirectedGraph
        :members:
 
+
 Heap
 ----
 

docs/Pathing.rst

@@ -0,0 +1,76 @@
+====
+Pathing
+====
+
+Some pathfinding algorithms and their implementations
+
+Quick Start Guide
+-----------------
+
+.. code-block:: python
+
+    # import the required pathing algorithm
+    from pygorithm.pathing import dijkstra
+    
+    # import a graph data structure
+    from pygorithm.data_structures import graph
+    
+    # initialize the graph with nodes from (0, 0) to (4, 4)
+    # with weight corresponding to distance (orthogonal 
+    # is 1, diagonal is sqrt(2))
+    my_graph = graph.WeightedUndirectedGraph()
+    my_graph.gridify(5, 1)
+    
+    # make the graph more interesting by removing along the 
+    # x=2 column except for (2,4)
+    my_graph.remove_edge((2, 0))
+    my_graph.remove_edge((2, 1))
+    my_graph.remove_edge((2, 2))
+    my_graph.remove_edge((2, 3))
+    
+    # calculate a path
+    my_path = dijkstra.find_path(my_graph, (0, 0), (3, 0))
+    
+    # print path
+    print(' -> '.join(my_path)) 
+    # (0, 0) -> (1, 1) -> (0, 2) -> (1, 3) -> (2, 4) -> (3, 3) -> (3, 2) -> (3, 1) -> (3, 0)
+    
+Features
+--------
+
+* Algorithms available:
+    - Dijkstra (dijkstra)
+
+
+* To see all the available functions in a module there is a `modules()` function available. For example,
+
+.. code:: python
+
+    >>> from pygorithm.pathfinding import modules
+    >>> modules.modules()
+    ['dijkstra']
+
+* Get the code used for any of the algorithm
+
+.. code-block:: python
+
+    from pygorithm.pathing import dijkstra
+
+    # for printing the source code of Dijkstra object
+    print(dijkstra.get_code())
+
+Dijkstra
+---
+
+* Functions and their uses
+
+.. function:: dijkstra.find_path(pygorithm.data_structures.WeightedUndirectedGraph, vertex, vertex)
+
+- **pygorithm.data_structures.WeightedUndirectedGraph** : acts like an object with `graph` (see WeightedUndirectedGraph)
+- **vertex** : any hashable type for the start of the path
+- **vertex** : any hashable type for the end of the path
+- **Return Value**    : returns a `List` of vertexes (of the same type as the graph) starting with from and going to to. This algorithm does *not* respect weights.
+
+.. function:: dijkstra.get_code()
+
+- **Return Value**    : returns the code for the ``Dijkstra`` object

docs/index.rst

@@ -27,6 +27,7 @@ Quick Links
    Data_Structure
    Fibonacci
    Math
+   Pathing
 
 Quick Start Guide
 -----------------

pygorithm/__init__.py

@@ -26,6 +26,7 @@
 Songzhuozhuo 'souo'
 Emil 'Skeen' Madsen
 Ian 'IanDoarn' Doarn
+Timothy 'Tjsretchalot' Moore
 
 """
 
@@ -51,7 +52,8 @@
     "dstark85",
     "Songzhuozhuo 'souo'",
     "Emil 'Skeen' Madsen",
-    "Ian 'IanDoarn' Doarn"
+    "Ian 'IanDoarn' Doarn",
+    "Timothy 'Tjstretchalot' Moore"
 ]
 
 __all__ = [
@@ -60,5 +62,6 @@
     'math',
     'searching',
     'sorting',
-    'string'
+    'string',
+    'pathing',
 ]

pygorithm/data_structures/graph.py

@@ -4,6 +4,7 @@
 """
 from collections import defaultdict
 import inspect
+import math
 
 
 class Graph(object):
@@ -14,14 +15,14 @@ class Graph(object):
     def __init__(self):
         self.graph = defaultdict(list)
         self.count = 0
-
+    
     def print_graph(self):
         """
         Prints the contents of the graph
         """
         for i in self.graph:
             print(i, '->', ' -> '.join([str(j) for j in self.graph[i]]))
-
+    
     def add_edge(self, from_vertex, to_vertex):
         """
         Adds an edge in the graph
@@ -121,7 +122,117 @@ def kruskal_code(cls):
         """
         return inspect.getsource(cls.kruskal_mst)
 
-
+class WeightedUndirectedGraph(object):
+    """WeightedUndirectedGraph object
+    A graph with a numerical value (weight) on edges, which
+    is the same for both directions in an undirected graph.
+    """
+    
+    def __init__(self):
+        self.graph = {}
+        self.weights = {}
+        
+    def add_edge(self, u, v, weight):
+        """
+        Adds the specified edge to this graph. If the edge already exists,
+        this will only modify the weight (not create duplicates).
+        :param u: from vertex
+        :param v: to vertex
+        :param weight: weight of the edge - type : numeric
+        """
+        
+        changing_weight = (u, v) in self.weights.keys()
+        
+        self.weights[(u, v)] = weight
+        self.weights[(v, u)] = weight
+        
+        if changing_weight:
+            return
+            
+        if u in self.graph.keys():
+            self.graph[u].append(v)
+        else:
+            self.graph[u] = [v]
+            
+        if v in self.graph.keys():
+            self.graph[v].append(u)
+        else:
+            self.graph[v] = [u]
+    
+    def get_edge_weight(self, u, v):
+        """
+        Gets the weight between u and v if such an edge
+        exists, or None if it does not.
+        :param u: one edge
+        :param v: the other edge
+        :return: numeric or None
+        """
+        return self.weights.get((u, v), None)
+            
+    def remove_edge(self, edge, other_edge_or_none=None):
+        """
+        Removes the specified edge from the grid entirely or,
+        if specified, the connection with one other edge.
+        Behavior is undefined if the connection does not
+        exist.
+        :param edge: the edge to remove
+        :param other_edge_or_none: an edge connected to edge or none
+        """
+        
+        if other_edge_or_none is not None:
+            del self.weights[(edge, other_edge_or_none)]
+            del self.weights[(other_edge_or_none, edge)]
+            
+            edge_list = self.graph[edge]
+            other_edge_list = self.graph[other_edge_or_none]
+            
+            if len(edge_list) == 1:
+                del self.graph[edge]
+            else:
+                self.graph[edge].remove(other_edge_or_none)
+                
+            if len(other_edge_list) == 1:
+                del self.graph[other_edge_or_none]
+            else:
+                self.graph[other_edge_or_none].remove(edge)
+        else:
+            edge_list = self.graph[edge]
+            del self.graph[edge]
+            for other_edge in edge_list:
+                del self.weights[(edge, other_edge)]
+                del self.weights[(other_edge, edge)]
+                
+                other_edge_list = self.graph[other_edge]
+                if len(other_edge_list) == 1:
+                    del self.graph[other_edge]
+                else:
+                    other_edge_list.remove(edge)
+        
+        
+    def gridify(self, size, weight):
+        """
+        Constructs connections from a square grid starting at (0, 0)
+        until (size-1, size-1) with connections between adjacent and 
+        diagonal nodes. Diagonal nodes have a weight of weight*sqrt(2)
+        :param size: the size of the square grid to construct - type : integer
+        :param weight: the weight between orthogonal nodes. - type: numeric
+        :return: None
+        """
+        rt2 = math.sqrt(2)
+        acceptable_offsets = [ 
+            (-1, -1, rt2), (-1, 0, 1), (-1, 1, rt2), 
+            (0, -1, 1), (0, 1, 1), 
+            (1, -1, rt2), (1, 0, 1), (1, 1, rt2)
+        ]
+        
+        for x in range(0, size):
+            for y in range(0, size):
+                for offset in acceptable_offsets:
+                    nx = x + offset[0]
+                    ny = y + offset[1]
+                    if nx >= 0 and ny >= 0 and nx < size and ny < size:
+                        self.add_edge((x, y), (nx, ny), weight * offset[2])     
+                        
 class TopologicalSort(Graph):
 
     def topological_sort(self):
@@ -241,14 +352,14 @@ class CheckCycleUndirectedGraph(object):
     def __init__(self):
         self.graph = {}
         self.count = 0
-
+    
     def print_graph(self):
         """
         for printing the contents of the graph
         """
         for i in self.graph:
             print(i, '->', ' -> '.join([str(j) for j in self.graph[i]]))
-
+    
     def add_edge(self, from_vertex, to_vertex):
         """
         for adding the edge between two vertices

pygorithm/pathing/__init__.py

@@ -0,0 +1,8 @@
+"""
+Collection of pathfinding examples
+"""
+from . import dijkstra
+
+__all__ = [
+    'dijkstra'
+]

pygorithm/pathing/dijkstra.py

@@ -0,0 +1,61 @@
+import heapq
+class Dijkstra(object):
+    """Dijkstra object
+    Finds the optimal path between two nodes on
+    a graph."""
+    
+    def __init__(self):
+        pass
+    
+    def reverse_path(self, node):
+        result = []
+        while node is not None:
+            result.insert(0, node['vertex'])
+            node = node['parent']
+        return result
+        
+    def find_path(self, graph, start, end):
+        """
+        Calculates the optimal path from start to end
+        on the graph. Weights are ignored.
+        
+        :param graph: object contains `graphs` as per pygorithm.data_structures.WeightedUndirectedGraph
+                      weights are ignored.
+        :param start: the start vertex (which is the same type of the verticies in the graph)
+        :param end:   the end vertex (which is the same type of the vertices in the graph)
+        :return:      a list starting with `start` and ending with `end`, or None if no path is possible.
+        """
+        
+        open = []
+        closed = set()
+        
+        # the first element in the tuple is the distance from the source. This is used as the primary
+        # key for sorting. The second element in the tuple is just a counter and is used to avoid having
+        # to hash the dictionary when the distance from the source is not unique.
+        
+        counter = 0
+        heapq.heappush(open, (0, counter, { 'vertex': start, 'parent': None }))
+        counter += 1
+        
+        while len(open) > 0:
+            current = heapq.heappop(open)
+            closed.update(current[2]['vertex'])
+            
+            if current[2]['vertex'] == end:
+                return self.reverse_path(current[2])
+            
+            neighbors = graph.graph[current[2]['vertex']]
+            for neighbor in neighbors:
+                if neighbor not in closed:
+                    heapq.heappush(open, (current[0] + 1, counter, { 'vertex': neighbor, 'parent': current[2] }))
+                    counter += 1
+            
+        
+        return None
+    
+    @staticmethod
+    def get_code(self):
+        """
+        returns the code for the current class
+        """
+        return inspect.getsource(Dijkstra)