scgraph 2.7.0__tar.gz → 2.8.0__tar.gz

{scgraph-2.7.0/scgraph.egg-info → scgraph-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scgraph
-Version: 2.7.0
+Version: 2.8.0
 Summary: Determine an approximate route between two points on earth.
 Author-email: Connor Makowski <conmak@mit.edu>
 Project-URL: Homepage, https://github.com/connor-makowski/scgraph
@@ -41,9 +41,10 @@ Low Level: https://connor-makowski.github.io/scgraph/scgraph/core.html
         - Algorithms:
             - Dijkstra's algorithm (Modified for sparse networks)
                 - Modified to support sparse network data structures
-            - Makowski's Modified Sparse Dijkstra algorithm
-                - Modified for O(n) performance on particularly sparse networks
-            - A* algorithm (Extension of Makowski's Modified Sparse Dijkstra)
+            - Modified Sparse Dijkstra algorithm
+                - Modified for O((n+m)log(n)) performance where n is the number of nodes and m is the number of edges
+                - Uses a priority queue to improve performance on large graphs
+            - A* algorithm (Extension of the Modified Sparse Dijkstra)
                 - Uses a heuristic function to improve performance on large graphs
                     - Note: The heuristic function is optional and defaults to Dijkstra's algorithm
             - Possible future support for other algorithms

{scgraph-2.7.0 → scgraph-2.8.0}/README.md

@@ -25,9 +25,10 @@ Low Level: https://connor-makowski.github.io/scgraph/scgraph/core.html
         - Algorithms:
             - Dijkstra's algorithm (Modified for sparse networks)
                 - Modified to support sparse network data structures
-            - Makowski's Modified Sparse Dijkstra algorithm
-                - Modified for O(n) performance on particularly sparse networks
-            - A* algorithm (Extension of Makowski's Modified Sparse Dijkstra)
+            - Modified Sparse Dijkstra algorithm
+                - Modified for O((n+m)log(n)) performance where n is the number of nodes and m is the number of edges
+                - Uses a priority queue to improve performance on large graphs
+            - A* algorithm (Extension of the Modified Sparse Dijkstra)
                 - Uses a heuristic function to improve performance on large graphs
                     - Note: The heuristic function is optional and defaults to Dijkstra's algorithm
             - Possible future support for other algorithms
@@ -363,4 +364,4 @@ Make sure Docker is installed and running on a Unix system (Linux, MacOS, WSL2).
 
 
 ## Attributions and Thanks
-Originally inspired by [searoute](https://github.com/genthalili/searoute-py) including the use of one of their [datasets](https://github.com/genthalili/searoute-py/blob/main/searoute/data/marnet_densified_v2_old.geojson) that has been modified to work properly with this package.
+Originally inspired by [searoute](https://github.com/genthalili/searoute-py) including the use of one of their [datasets](https://github.com/genthalili/searoute-py/blob/main/searoute/data/marnet_densified_v2_old.geojson) that has been modified to work properly with this package.

{scgraph-2.7.0 → scgraph-2.8.0}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scgraph"
-version = "2.7.0"
+version = "2.8.0"
 description = "Determine an approximate route between two points on earth."
 authors = [
     {name="Connor Makowski", email="conmak@mit.edu"}

{scgraph-2.7.0 → scgraph-2.8.0}/scgraph/__init__.py

@@ -26,9 +26,10 @@ Low Level: https://connor-makowski.github.io/scgraph/scgraph/core.html
         - Algorithms:
             - Dijkstra's algorithm (Modified for sparse networks)
                 - Modified to support sparse network data structures
-            - Makowski's Modified Sparse Dijkstra algorithm
-                - Modified for O(n) performance on particularly sparse networks
-            - A* algorithm (Extension of Makowski's Modified Sparse Dijkstra)
+            - Modified Sparse Dijkstra algorithm
+                - Modified for O((n+m)log(n)) performance where n is the number of nodes and m is the number of edges
+                - Uses a priority queue to improve performance on large graphs
+            - A* algorithm (Extension of the Modified Sparse Dijkstra)
                 - Uses a heuristic function to improve performance on large graphs
                     - Note: The heuristic function is optional and defaults to Dijkstra's algorithm
             - Possible future support for other algorithms
@@ -364,7 +365,9 @@ Make sure Docker is installed and running on a Unix system (Linux, MacOS, WSL2).
 
 
 ## Attributions and Thanks
-Originally inspired by [searoute](https://github.com/genthalili/searoute-py) including the use of one of their [datasets](https://github.com/genthalili/searoute-py/blob/main/searoute/data/marnet_densified_v2_old.geojson) that has been modified to work properly with this package."""
+Originally inspired by [searoute](https://github.com/genthalili/searoute-py) including the use of one of their [datasets](https://github.com/genthalili/searoute-py/blob/main/searoute/data/marnet_densified_v2_old.geojson) that has been modified to work properly with this package.
+"""
 
-from .core import Graph, GeoGraph
+from .graph import Graph
+from .geograph import GeoGraph
 from .grid import GridGraph

scgraph-2.8.0/scgraph/core.py

@@ -0,0 +1,7 @@
+# This file just imports the necessary modules to allow for backwards compatibility
+from scgraph.graph import Graph
+from scgraph.geograph import (
+    GeoGraph,
+    load_geojson_as_geograph,
+    get_multi_path_geojson,
+)

scgraph-2.7.0/scgraph/core.py → scgraph-2.8.0/scgraph/geograph.py

@@ -1,424 +1,7 @@
 from .utils import haversine, distance_converter, get_line_path, cheap_ruler
 import json
-from heapq import heappop, heappush
 
-
-class Graph:
-    @staticmethod
-    def validate_graph(
-        graph: list[dict[int, int | float]],
-        check_symmetry: bool = True,
-        check_connected: bool = True,
-    ) -> None:
-        """
-        Function:
-
-        - Validate that a graph is properly formatted
-
-        Required Arguments:
-
-        - `graph`:
-            - Type: list of dictionaries with integer keys and integer or float values
-            - What: A list of dictionaries where the indicies are origin node ids and the values are dictionaries of destination node indices and graph weights
-            - Note: All nodes must be included as origins in the graph regardless of if they have any connected destinations
-            - EG:
-            ```
-                [
-                    # From London (index 0)
-                    {
-                        # To Paris (index 1)
-                        1: 311,
-                    },
-                    # From Paris (index 1)
-                    {
-                        # To London (index 0)
-                        0: 311,
-                        # To Berlin (index 2)
-                        2: 878,
-                        # To Rome (index 3)
-                        3: 1439,
-                        # To Madrid (index 4)
-                        4: 1053
-                    },
-                    # From Berlin (index 2)
-                    {
-                        # To Paris (index 1)
-                        1: 878,
-                        # To Rome (index 3)
-                        3: 1181,
-                    },
-                    # From Rome (index 3)
-                    {
-                        # To Paris (index 1)
-                        1: 1439,
-                        # To Berlin (index 2)
-                        2: 1181,
-                    },
-                    # From Madrid (index 4)
-                    {
-                        # To Paris (index 1)
-                        1: 1053,
-                        # To Lisbon (index 5)
-                        5: 623
-                    },
-                    # From Lisbon (index 5)
-                    {
-                        # To Madrid (index 4)
-                        4: 623
-                    }
-                ]
-            ```
-
-        Optional Arguments:
-
-        - `check_symmetry`
-            - Type: bool
-            - What: Whether to check that the graph is symmetric
-            - Default: True
-            - Note: This is forced to True if `check_connected` is True
-        - `check_connected`
-            - Type: bool
-            - What: Whether to check that the graph is fully connected
-            - Default: True
-            - Note: For computational efficiency, only symmetric graphs are checked for connectivity
-            - Note: If this is True, `check_symmetry` is forced to True and the graph will be checked for symmetry prior to checking for connectivity
-        """
-        check_symmetry = check_symmetry or check_connected
-        assert isinstance(graph, list), "Your graph must be a list"
-        len_graph = len(graph)
-        for origin_id, origin_dict in enumerate(graph):
-            assert isinstance(
-                origin_dict, dict
-            ), f"Your graph must be a list of dictionaries but the value for origin {origin_id} is not a dictionary"
-            destinations = list(origin_dict.keys())
-            lengths = list(origin_dict.values())
-            assert all(
-                [
-                    (isinstance(i, int) and i >= 0 and i < len_graph)
-                    for i in destinations
-                ]
-            ), f"Destination ids must be non-negative integers and equivalent to an existing index, but graph[{origin_id}] has an error in the destination ids"
-            assert all(
-                [(isinstance(i, (int, float)) and i >= 0) for i in lengths]
-            ), f"Distances must be integers or floats, but graph[{origin_id}] contains a non-integer or non-float distance"
-            if check_symmetry:
-                for destination_id, distance in origin_dict.items():
-                    assert (
-                        graph[destination_id].get(origin_id) == distance
-                    ), f"Your graph is not symmetric, the distance from node {origin_id} to node {destination_id} is {distance} but the distance from node {destination_id} to node {origin_id} is {graph.get(destination_id, {}).get(origin_id)}"
-        if check_connected:
-            assert Graph.validate_connected(
-                graph
-            ), "Your graph is not fully connected"
-
-    @staticmethod
-    def validate_connected(
-        graph: list[dict[int, int | float]], origin_id: int = 0
-    ) -> bool:
-        """
-        Function:
-
-        - Validate that a graph is fully connected
-            - This means that every node in the graph has a path to every other node in the graph
-            - Note: This assumes that the graph is symmetric
-        - Return True if the graph is fully connected and False if it is not
-
-        Required Arguments:
-
-        - `graph`:
-            - Type: list of dictionaries
-            - See: https://connor-makowski.github.io/scgraph/scgraph/core.html#Graph.validate_graph
-
-        Optional Arguments:
-
-        - `origin_id`
-            - Type: int
-            - What: The id of the origin node from which to start the connectivity check
-            - Default: 0
-        """
-        visited = [0] * len(graph)
-        open_leaves = [origin_id]
-
-        while open_leaves:
-            current_id = open_leaves.pop()
-            visited[current_id] = 1
-            for connected_id, connected_distance in graph[current_id].items():
-                if visited[connected_id] == 0:
-                    open_leaves.append(connected_id)
-        return min(visited) == 1
-
-    @staticmethod
-    def input_check(
-        graph: list[dict[int, int | float]], origin_id: int, destination_id: int
-    ) -> None:
-        """
-        Function:
-
-        - Check that the inputs passed to the shortest path algorithm are valid
-        - Raises an exception if the inputs passed are not valid
-
-        Required Arguments:
-
-        - `graph`:
-            - Type: list of dictionaries
-            - See: https://connor-makowski.github.io/scgraph/scgraph/core.html#Graph.validate_graph
-        - `origin_id`
-            - Type: int
-            - What: The id of the origin node from the graph dictionary to start the shortest path from
-        - `destination_id`
-            - Type: int
-            - What: The id of the destination node from the graph dictionary to end the shortest path at
-
-        Optional Arguments:
-
-        - None
-        """
-        if (
-            not isinstance(origin_id, int)
-            and origin_id < len(graph)
-            and origin_id >= 0
-        ):
-            raise Exception(f"Origin node ({origin_id}) is not in the graph")
-        if (
-            not isinstance(destination_id, int)
-            and origin_id < len(graph)
-            and origin_id >= 0
-        ):
-            raise Exception(
-                f"Destination node ({destination_id}) is not in the graph"
-            )
-
-    @staticmethod
-    def dijkstra(
-        graph: list[dict[int, int | float]], origin_id: int, destination_id: int
-    ) -> dict:
-        """
-        Function:
-
-        - Identify the shortest path between two nodes in a sparse network graph using a modified dijkstra algorithm
-            - Modifications allow for a sparse distance matrix to be used instead of a dense distance matrix
-            - This can dramatically reduce the memory and compute requirements of the algorithm
-            - This algorithm runs in O(n^2) time where n is the number of nodes in the graph
-        - Return a dictionary of various path information including:
-            - `id_path`: A list of node ids in the order they are visited
-            - `path`: A list of node dictionaries (lat + long) in the order they are visited
-
-        Required Arguments:
-
-        - `graph`:
-            - Type: list of dictionaries
-            - See: https://connor-makowski.github.io/scgraph/scgraph/core.html#Graph.validate_graph
-        - `origin_id`
-            - Type: int
-            - What: The id of the origin node from the graph dictionary to start the shortest path from
-        - `destination_id`
-            - Type: int
-            - What: The id of the destination node from the graph dictionary to end the shortest path at
-
-        Optional Arguments:
-
-        - None
-        """
-        Graph.input_check(
-            graph=graph, origin_id=origin_id, destination_id=destination_id
-        )
-        distance_matrix = [float("inf")] * len(graph)
-        branch_tip_distances = [float("inf")] * len(graph)
-        predecessor = [-1] * len(graph)
-
-        distance_matrix[origin_id] = 0
-        branch_tip_distances[origin_id] = 0
-
-        while True:
-            current_distance = min(branch_tip_distances)
-            if current_distance == float("inf"):
-                raise Exception(
-                    "Something went wrong, the origin and destination nodes are not connected."
-                )
-            current_id = branch_tip_distances.index(current_distance)
-            branch_tip_distances[current_id] = float("inf")
-            if current_id == destination_id:
-                break
-            for connected_id, connected_distance in graph[current_id].items():
-                possible_distance = current_distance + connected_distance
-                if possible_distance < distance_matrix[connected_id]:
-                    distance_matrix[connected_id] = possible_distance
-                    predecessor[connected_id] = current_id
-                    branch_tip_distances[connected_id] = possible_distance
-
-        output_path = [current_id]
-        while predecessor[current_id] != -1:
-            current_id = predecessor[current_id]
-            output_path.append(current_id)
-
-        output_path.reverse()
-
-        return {
-            "path": output_path,
-            "length": distance_matrix[destination_id],
-        }
-
-    @staticmethod
-    def dijkstra_makowski(
-        graph: list[dict[int, int | float]], origin_id: int, destination_id: int
-    ) -> dict:
-        """
-        Function:
-
-        - Identify the shortest path between two nodes in a sparse network graph using Makowski's modified Dijkstra algorithm
-            - Modifications allow for a sparse distance matrix to be used instead of a dense distance matrix
-            - Improvements include only computing future potential nodes based on the open leaves for each branch
-                - Open leaves are nodes that have not been visited yet but are adjacent to other visited nodes
-            - This can dramatically reduce the memory and compute requirements of the algorithm
-            - For particularly sparse graphs, this algorithm runs close to O(n log n) time
-                - Where n is the number of nodes in the graph
-            - For dense graphs, this algorithm runs closer to O(n^2) time (similar to the standard Dijkstra algorithm)
-                - Where n is the number of nodes in the graph
-        - Return a dictionary of various path information including:
-            - `id_path`: A list of node ids in the order they are visited
-            - `path`: A list of node dictionaries (lat + long) in the order they are visited
-
-        Required Arguments:
-
-        - `graph`:
-            - Type: list of dictionaries
-            - See: https://connor-makowski.github.io/scgraph/scgraph/core.html#Graph.validate_graph
-        - `origin_id`
-            - Type: int
-            - What: The id of the origin node from the graph dictionary to start the shortest path from
-        - `destination_id`
-            - Type: int
-            - What: The id of the destination node from the graph dictionary to end the shortest path at
-
-        Optional Arguments:
-
-        - None
-        """
-        # Input Validation
-        Graph.input_check(
-            graph=graph, origin_id=origin_id, destination_id=destination_id
-        )
-        # Variable Initialization
-        distance_matrix = [float("inf")] * len(graph)
-        distance_matrix[origin_id] = 0
-        open_leaves = []
-        heappush(open_leaves, (0, origin_id))
-        predecessor = [-1] * len(graph)
-
-        while open_leaves:
-            current_distance, current_id = heappop(open_leaves)
-            if current_id == destination_id:
-                break
-            for connected_id, connected_distance in graph[current_id].items():
-                possible_distance = current_distance + connected_distance
-                if possible_distance < distance_matrix[connected_id]:
-                    distance_matrix[connected_id] = possible_distance
-                    predecessor[connected_id] = current_id
-                    heappush(open_leaves, (possible_distance, connected_id))
-        if current_id != destination_id:
-            raise Exception(
-                "Something went wrong, the origin and destination nodes are not connected."
-            )
-
-        output_path = [current_id]
-        while predecessor[current_id] != -1:
-            current_id = predecessor[current_id]
-            output_path.append(current_id)
-
-        output_path.reverse()
-
-        return {
-            "path": output_path,
-            "length": distance_matrix[destination_id],
-        }
-
-    @staticmethod
-    def a_star(
-        graph: list[dict[int, int | float]],
-        origin_id: int,
-        destination_id: int,
-        heuristic_fn=None,
-    ) -> dict:
-        """
-        Function:
-
-        - Identify the shortest path between two nodes in a sparse network graph using an A* extension of Makowski's modified Dijkstra algorithm
-        - Return a dictionary of various path information including:
-            - `id_path`: A list of node ids in the order they are visited
-            - `path`: A list of node dictionaries (lat + long) in the order they are visited
-
-        Required Arguments:
-
-        - `graph`:
-            - Type: list of dictionaries
-            - See: https://connor-makowski.github.io/scgraph/scgraph/core.html#Graph.validate_graph
-        - `origin_id`
-            - Type: int
-            - What: The id of the origin node from the graph dictionary to start the shortest path from
-        - `destination_id`
-            - Type: int
-            - What: The id of the destination node from the graph dictionary to end the shortest path at
-        - `heuristic_fn`
-            - Type: function
-            - What: A heuristic function that takes two node ids and returns an estimated distance between them
-            - Note: If None, returns the shortest path using Makowski's modified Dijkstra algorithm
-            - Default: None
-
-        Optional Arguments:
-
-        - None
-        """
-        if heuristic_fn is None:
-            return Graph.dijkstra_makowski(
-                graph=graph,
-                origin_id=origin_id,
-                destination_id=destination_id,
-            )
-        # Input Validation
-        Graph.input_check(
-            graph=graph, origin_id=origin_id, destination_id=destination_id
-        )
-        # Variable Initialization
-        distance_matrix = [float("inf")] * len(graph)
-        distance_matrix[origin_id] = 0
-        open_leaves = []
-        heappush(open_leaves, (0, origin_id))
-        predecessor = [-1] * len(graph)
-
-        while open_leaves:
-            current_id = heappop(open_leaves)[1]
-            if current_id == destination_id:
-                break
-            current_distance = distance_matrix[current_id]
-            for connected_id, connected_distance in graph[current_id].items():
-                possible_distance = current_distance + connected_distance
-                if possible_distance < distance_matrix[connected_id]:
-                    distance_matrix[connected_id] = possible_distance
-                    predecessor[connected_id] = current_id
-                    heappush(
-                        open_leaves,
-                        (
-                            possible_distance
-                            + heuristic_fn(connected_id, destination_id),
-                            connected_id,
-                        ),
-                    )
-        if current_id != destination_id:
-            raise Exception(
-                "Something went wrong, the origin and destination nodes are not connected."
-            )
-
-        output_path = [current_id]
-        while predecessor[current_id] != -1:
-            current_id = predecessor[current_id]
-            output_path.append(current_id)
-
-        output_path.reverse()
-
-        return {
-            "path": output_path,
-            "length": distance_matrix[destination_id],
-        }
+from scgraph.graph import Graph
 
 
 class GeoGraph:
@@ -540,6 +123,24 @@ class GeoGraph:
         origin_id: int,
         destination_id: int,
     ):
+        """
+        Function:
+
+        - Calculate the haversine distance between two points on the Earth.
+
+        Required Arguments:
+
+        - `origin_id`
+            - Type: int
+            - What: The id of the origin node in the graph
+        - `destination_id`
+            - Type: int
+            - What: The id of the destination node in the graph
+
+        Optional Arguments:
+
+        - None
+        """
         return haversine(
             origin=self.nodes[origin_id],
             destination=self.nodes[destination_id],
@@ -552,6 +153,26 @@ class GeoGraph:
         origin_id: int,
         destination_id: int,
     ):
+        """
+        Function:
+
+        - Calculate the distance between two points on the Earth using the cheap ruler algorithm.
+        - This is based off of Mapbox's cheap ruler algorithm which is a fast approximation of the haversine distance
+        - It has modifications to support distances across the antimeridian
+
+        Required Arguments:
+
+        - `origin_id`
+            - Type: int
+            - What: The id of the origin node in the graph
+        - `destination_id`
+            - Type: int
+            - What: The id of the destination node in the graph
+
+        Optional Arguments:
+
+        - None
+        """
         return cheap_ruler(
             origin=self.nodes[origin_id],
             destination=self.nodes[destination_id],
@@ -719,7 +340,7 @@ class GeoGraph:
                 **algorithm_kwargs,
             )
             output["coordinate_path"] = self.get_coordinate_path(output["path"])
-            output["length"] = self.adujust_circuity_length(
+            output["length"] = self.adjust_circuity_length(
                 output=output,
                 node_addition_circuity=node_addition_circuity,
                 off_graph_circuity=off_graph_circuity,
@@ -749,7 +370,7 @@ class GeoGraph:
                 self.remove_appended_node()
             raise e
 
-    def adujust_circuity_length(
+    def adjust_circuity_length(
         self,
         output: dict,
         node_addition_circuity: [float | int],
@@ -789,6 +410,15 @@ class GeoGraph:
                 4,
             )
 
+    def adujust_circuity_length(self, *args, **kwargs):
+        """
+        Maintain backwards compatibility with the old method that had a typo.
+
+        This is now just an alias for `adjust_circuity_length`.
+        """
+        # TODO: Remove in next major release
+        return self.adjust_circuity_length(*args, **kwargs)
+
     def get_coordinate_path(self, path: list[int]) -> list[dict[float | int]]:
         """
         Function: