scgraph 2.6.0__tar.gz → 2.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scgraph
-Version: 2.6.0
+Version: 2.7.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
@@ -43,6 +43,9 @@ Low Level: https://connor-makowski.github.io/scgraph/scgraph/core.html
                 - 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)
+                - 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
         - Distances:
             - Uses the [haversine formula](https://en.wikipedia.org/wiki/Haversine_formula) to calculate the distance between two points on earth
@@ -89,7 +92,8 @@ In this case, calculate the shortest maritime path between Shanghai, China and S
 # Use a maritime network geograph
 from scgraph.geographs.marnet import marnet_geograph
 
-# Get the shortest path between
+# Get the shortest maritime path between Shanghai, China and Savannah, Georgia, USA
+# Note: The origin and destination nodes can be any latitude / longitude pair
 output = marnet_geograph.get_shortest_path(
     origin_node={"latitude": 31.23,"longitude": 121.47},
     destination_node={"latitude": 32.08,"longitude": -81.09},
@@ -194,11 +198,16 @@ Using `scgraph_data` geographs:
 - Note: Make sure to install the `scgraph_data` package before using these geographs
 ```py
 from scgraph_data.world_railways import world_railways_geograph
+from scgraph import Graph
 
 # Get the shortest path between Kalamazoo Michigan and Detroit Michigan by Train
 output = world_railways_geograph.get_shortest_path(
     origin_node={"latitude": 42.29,"longitude": -85.58},
-    destination_node={"latitude": 42.33,"longitude": -83.05}
+    destination_node={"latitude": 42.33,"longitude": -83.05},
+    # Optional: Use the A* algorithm
+    algorithm_fn=Graph.a_star,
+    # Optional: Pass the haversine function as the heuristic function to the A* algorithm
+    algorithm_kwargs={"heuristic_fn": world_railways_geograph.haversine},
 )
 ```
 

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

@@ -27,6 +27,9 @@ Low Level: https://connor-makowski.github.io/scgraph/scgraph/core.html
                 - 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)
+                - 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
         - Distances:
             - Uses the [haversine formula](https://en.wikipedia.org/wiki/Haversine_formula) to calculate the distance between two points on earth
@@ -73,7 +76,8 @@ In this case, calculate the shortest maritime path between Shanghai, China and S
 # Use a maritime network geograph
 from scgraph.geographs.marnet import marnet_geograph
 
-# Get the shortest path between
+# Get the shortest maritime path between Shanghai, China and Savannah, Georgia, USA
+# Note: The origin and destination nodes can be any latitude / longitude pair
 output = marnet_geograph.get_shortest_path(
     origin_node={"latitude": 31.23,"longitude": 121.47},
     destination_node={"latitude": 32.08,"longitude": -81.09},
@@ -178,11 +182,16 @@ Using `scgraph_data` geographs:
 - Note: Make sure to install the `scgraph_data` package before using these geographs
 ```py
 from scgraph_data.world_railways import world_railways_geograph
+from scgraph import Graph
 
 # Get the shortest path between Kalamazoo Michigan and Detroit Michigan by Train
 output = world_railways_geograph.get_shortest_path(
     origin_node={"latitude": 42.29,"longitude": -85.58},
-    destination_node={"latitude": 42.33,"longitude": -83.05}
+    destination_node={"latitude": 42.33,"longitude": -83.05},
+    # Optional: Use the A* algorithm
+    algorithm_fn=Graph.a_star,
+    # Optional: Pass the haversine function as the heuristic function to the A* algorithm
+    algorithm_kwargs={"heuristic_fn": world_railways_geograph.haversine},
 )
 ```
 

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

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

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

@@ -28,6 +28,9 @@ Low Level: https://connor-makowski.github.io/scgraph/scgraph/core.html
                 - 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)
+                - 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
         - Distances:
             - Uses the [haversine formula](https://en.wikipedia.org/wiki/Haversine_formula) to calculate the distance between two points on earth
@@ -74,7 +77,8 @@ In this case, calculate the shortest maritime path between Shanghai, China and S
 # Use a maritime network geograph
 from scgraph.geographs.marnet import marnet_geograph
 
-# Get the shortest path between
+# Get the shortest maritime path between Shanghai, China and Savannah, Georgia, USA
+# Note: The origin and destination nodes can be any latitude / longitude pair
 output = marnet_geograph.get_shortest_path(
     origin_node={"latitude": 31.23,"longitude": 121.47},
     destination_node={"latitude": 32.08,"longitude": -81.09},
@@ -179,11 +183,16 @@ Using `scgraph_data` geographs:
 - Note: Make sure to install the `scgraph_data` package before using these geographs
 ```py
 from scgraph_data.world_railways import world_railways_geograph
+from scgraph import Graph
 
 # Get the shortest path between Kalamazoo Michigan and Detroit Michigan by Train
 output = world_railways_geograph.get_shortest_path(
     origin_node={"latitude": 42.29,"longitude": -85.58},
-    destination_node={"latitude": 42.33,"longitude": -83.05}
+    destination_node={"latitude": 42.33,"longitude": -83.05},
+    # Optional: Use the A* algorithm
+    algorithm_fn=Graph.a_star,
+    # Optional: Pass the haversine function as the heuristic function to the A* algorithm
+    algorithm_kwargs={"heuristic_fn": world_railways_geograph.haversine},
 )
 ```
 

{scgraph-2.6.0 → scgraph-2.7.0}/scgraph/cache.py

@@ -31,6 +31,7 @@ class CacheGraph:
         destination_id: int,
         cache: bool = True,
         cache_for: str = "origin",
+        heuristic_fn=None,
     ):
         """
         Function:
@@ -50,6 +51,13 @@ class CacheGraph:
         - cache_for: Whether to cache the spanning tree for the origin or destination node
             - Default: 'origin'
             - Options: 'origin', 'destination'
+        - heuristic_fn: A heuristic function to use for the A* algorithm if cache is False and the origin or destination node is not in the cache
+            - Type: callable | None
+            - If None, the A* function will compute with Dijkstra's algorithm instead
+            - If a callable is provided, it should take two arguments: origin_id and destination_id
+              and return a float representing the heuristic distance between the two nodes
+              - Note: This distance should never be greater than the actual distance between the two nodes or you may get suboptimal paths
+
 
         """
         spanning_tree = self.cache.get(
@@ -68,11 +76,12 @@ class CacheGraph:
         if spanning_tree is not None:
             return SpanningTree.get_path(
                 origin_id=origin_id,
-                destionation_id=destination_id,
+                destination_id=destination_id,
                 spanning_tree=spanning_tree,
             )
-        return Graph.dijkstra_makowski(
+        return Graph.a_star(
             graph=self.graph,
             origin_id=origin_id,
             destination_id=destination_id,
+            heuristic_fn=heuristic_fn,
         )

{scgraph-2.6.0 → scgraph-2.7.0}/scgraph/core.py

@@ -1,4 +1,4 @@
-from .utils import haversine, hard_round, distance_converter, get_line_path
+from .utils import haversine, distance_converter, get_line_path, cheap_ruler
 import json
 from heapq import heappop, heappush
 
@@ -255,7 +255,7 @@ class Graph:
 
         return {
             "path": output_path,
-            "length": hard_round(4, distance_matrix[destination_id]),
+            "length": distance_matrix[destination_id],
         }
 
     @staticmethod
@@ -294,22 +294,99 @@ class Graph:
 
         - 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 True:
-            if len(open_leaves) == 0:
-                raise Exception(
-                    "Something went wrong, the origin and destination nodes are not connected."
-                )
-            current_distance, current_id = heappop(open_leaves)
+        while open_leaves:
+            current_id = heappop(open_leaves)[1]
             if current_id == destination_id:
                 break
             current_distance = distance_matrix[current_id]
@@ -318,7 +395,18 @@ class Graph:
                 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))
+                    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:
@@ -329,7 +417,7 @@ class Graph:
 
         return {
             "path": output_path,
-            "length": hard_round(4, distance_matrix[destination_id]),
+            "length": distance_matrix[destination_id],
         }
 
 
@@ -447,12 +535,38 @@ class GeoGraph:
             ]
         ), "Your nodes must be a list of lists where each sub list has a length of 2 with a latitude [-90,90] and longitude [-180,180] value"
 
+    def haversine(
+        self,
+        origin_id: int,
+        destination_id: int,
+    ):
+        return haversine(
+            origin=self.nodes[origin_id],
+            destination=self.nodes[destination_id],
+            units="km",
+            circuity=1,
+        )
+
+    def cheap_ruler(
+        self,
+        origin_id: int,
+        destination_id: int,
+    ):
+        return cheap_ruler(
+            origin=self.nodes[origin_id],
+            destination=self.nodes[destination_id],
+            units="km",
+            # Use a circuity factor of 0.95 to account for the fact that cheap_ruler can overestimate distances
+            circuity=0.9,
+        )
+
     def get_shortest_path(
         self,
         origin_node: dict[float | int],
         destination_node: dict[float | int],
         output_units: str = "km",
         algorithm_fn=Graph.dijkstra_makowski,
+        algorithm_kwargs: dict = dict(),
         off_graph_circuity: [float | int] = 1,
         node_addition_type: str = "quadrant",
         node_addition_circuity: [float | int] = 4,
@@ -505,6 +619,9 @@ class GeoGraph:
                         - See: https://connor-makowski.github.io/scgraph/scgraph/core.html#Graph.validate_graph
                     - `origin`: The id of the origin node from the graph dictionary to start the shortest path from
                     - `destination`: The id of the destination node from the graph dictionary to end the shortest path at
+        - `algorithm_kwargs`
+            - Type: dict
+            - What: Additional keyword arguments to pass to the algorithm function assuming it accepts them
         - `off_graph_circuity`
             - Type: int | float
             - What: The circuity factor to apply to any distance calculations between your origin and destination nodes and their connecting nodes in the graph
@@ -594,12 +711,12 @@ class GeoGraph:
             lat_lon_bound=node_addition_lat_lon_bound,
             node_addition_math=node_addition_math,
         )
-
         try:
             output = algorithm_fn(
                 graph=self.graph,
                 origin_id=origin_id,
                 destination_id=destination_id,
+                **algorithm_kwargs,
             )
             output["coordinate_path"] = self.get_coordinate_path(output["path"])
             output["length"] = self.adujust_circuity_length(

{scgraph-2.6.0 → scgraph-2.7.0}/scgraph/grid.py

@@ -1,5 +1,6 @@
 from scgraph.helpers.shape_mover_utils import ShapeMoverUtils
 from scgraph.cache import CacheGraph
+from typing import Literal
 
 
 class GridGraph:
@@ -101,6 +102,7 @@ class GridGraph:
             self.conn_data = conn_data
 
         self.graph = self.__create_graph__()
+        self.nodes = [self.__get_x_y__(idx) for idx in range(len(self.graph))]
         self.cacheGraph = CacheGraph(self.graph)
 
     def __get_idx__(self, x: int, y: int):
@@ -217,6 +219,12 @@ class GridGraph:
         Function:
 
         - Create a graph from the grid specifications
+
+        Returns:
+
+        - `graph`
+            - Type: list
+            - What: The adjacency list representation of the graph
         """
         ####################
         # Create a list of lists to hold all the possible connections in an easy to access/understand format
@@ -282,6 +290,34 @@ class GridGraph:
 
         return graph
 
+    def euclidean_heuristic(self, origin_id: int, destination_id: int) -> float:
+        """
+        Function:
+
+        - Calculate the Euclidean distance between two nodes in the grid graph
+
+        Required Arguments:
+
+        - `origin_id`
+            - Type: int
+            - What: The id of the origin node
+        - `destination_id`
+            - Type: int
+            - What: The id of the destination node
+
+        Returns:
+
+        - `distance`
+            - Type: float
+            - What: The Euclidean distance between the two nodes
+        """
+        origin_location = self.nodes[origin_id]
+        destination_location = self.nodes[destination_id]
+        return (
+            (origin_location[0] - destination_location[0]) ** 2
+            + (origin_location[1] - destination_location[1]) ** 2
+        ) ** 0.5
+
     def get_shortest_path(
         self,
         origin_node: dict[str, int] | tuple[int, int] | list[int],
@@ -290,6 +326,7 @@ class GridGraph:
         cache: bool = False,
         cache_for: str = "origin",
         output_path: bool = False,
+        heuristic_fn: callable | Literal["euclidean"] | None = "euclidean",
         **kwargs,
     ) -> dict:
         """
@@ -336,6 +373,13 @@ class GridGraph:
             - Type: bool
             - What: Whether to output the path as a list of graph idxs (mostly for debugging purposes)
             - Default: False
+        - `heuristic_fn`
+            - Type: callable | Literal['euclidean'] | None
+            - What: A heuristic function to use for the A* algorithm if caching is False
+            - Default: 'euclidean' (A predefined heuristic function that calculates the Euclidean distance for this grid graph)
+            - If None, the A* algorithm will not be used and the Dijkstra's algorithm will be used instead
+            - If a callable is provided, it should take two arguments: origin_id and destination_id and return a float representing the heuristic distance between the two nodes
+                - Note: This distance should never be greater than the actual distance between the two nodes or you may get suboptimal paths
         - `**kwargs`
             - Additional keyword arguments. These are included for forwards and backwards compatibility reasons, but are not currently used.
         """
@@ -369,6 +413,11 @@ class GridGraph:
             destination_id=destination_id,
             cache=cache,
             cache_for=cache_for,
+            heuristic_fn=(
+                self.euclidean_heuristic
+                if heuristic_fn == "euclidean"
+                else heuristic_fn
+            ),
         )
         output["coordinate_path"] = self.get_coordinate_path(
             output["path"], output_coordinate_path

{scgraph-2.6.0 → scgraph-2.7.0}/scgraph/spanning.py

@@ -40,20 +40,15 @@ class SpanningTree:
         # Input Validation
         assert isinstance(node_id, int), "node_id must be an integer"
         assert 0 <= node_id < len(graph), "node_id must be a valid node id"
+        # Variable Initialization
         distance_matrix = [float("inf")] * len(graph)
-        open_leaves = {}
-        predecessor = [-1] * len(graph)
-        visited = [0] * len(graph)
-
         distance_matrix[node_id] = 0
         open_leaves = []
         heappush(open_leaves, (0, node_id))
+        predecessor = [-1] * len(graph)
 
         while open_leaves:
             current_distance, current_id = heappop(open_leaves)
-            if visited[current_id]:
-                continue
-            visited[current_id] = True
             for connected_id, connected_distance in graph[current_id].items():
                 possible_distance = current_distance + connected_distance
                 if possible_distance < distance_matrix[connected_id]:
@@ -68,7 +63,7 @@ class SpanningTree:
         }
 
     @staticmethod
-    def get_path(origin_id: int, destionation_id: int, spanning_tree: dict):
+    def get_path(origin_id: int, destination_id: int, spanning_tree: dict):
         """
         Function:
 
@@ -78,10 +73,10 @@ class SpanningTree:
 
         Required Arguments:
 
-        - `origin_idx`
+        - `origin_id`
             - Type: int
             - What: The id of the origin node from the graph dictionary to start the shortest path from
-        - `destination_idx`
+        - `destination_id`
             - Type: int
             - What: The id of the destination node from the graph dictionary to end the shortest path at
         - `spanning_tree`
@@ -93,7 +88,7 @@ class SpanningTree:
         - None
         """
         spanning_id = spanning_tree["node_id"]
-        destination_distance = spanning_tree["distance_matrix"][destionation_id]
+        destination_distance = spanning_tree["distance_matrix"][destination_id]
         origin_distance = spanning_tree["distance_matrix"][origin_id]
 
         if destination_distance == float("inf") or origin_distance == float(
@@ -103,23 +98,23 @@ class SpanningTree:
                 "Something went wrong: One or both of the origin and destination nodes are not connected to this spanning tree."
             )
 
-        origin_to_spanning_id = []
-        current_id = origin_id
-        while current_id != spanning_id:
-            origin_to_spanning_id.append(current_id)
-            current_id = spanning_tree["predecessors"][current_id]
+        if spanning_id != origin_id and spanning_id != destination_id:
+            raise Exception(
+                "Something went wrong: Neither the origin nor the destination node is the same as the spanning node."
+            )
 
-        destination_to_spanning_id = []
-        current_id = destionation_id
+        current_id = origin_id if spanning_id != origin_id else destination_id
+        current_path = []
         while current_id != spanning_id:
-            destination_to_spanning_id.append(current_id)
+            current_path.append(current_id)
             current_id = spanning_tree["predecessors"][current_id]
-        # Reverse the destination path to get the correct order
-        destination_to_spanning_id.reverse()
-
+        current_path.append(spanning_id)
+        if spanning_id == origin_id:
+            current_path.reverse()
+            current_length = spanning_tree["distance_matrix"][destination_id]
+        else:
+            current_length = spanning_tree["distance_matrix"][origin_id]
         return {
-            "path": origin_to_spanning_id
-            + [spanning_id]
-            + destination_to_spanning_id,
-            "length": hard_round(4, origin_distance + destination_distance),
+            "path": current_path,
+            "length": hard_round(4, current_length),
         }

{scgraph-2.6.0 → scgraph-2.7.0}/scgraph/utils.py

@@ -1,5 +1,15 @@
 import math, json
 
+# Constants for haversine and cheap ruler calculations
+earth_radius = {
+    "km": 6371,
+    "m": 6371000,
+    "mi": 3959,
+    "ft": 3959 * 5280,
+}
+radians_per_degree = math.pi / 180  # radians per degree
+cheap_e2 = (1 / 298.257223563) * (2 - (1 / 298.257223563))
+
 
 def haversine(
     origin: list[float | int],
@@ -33,40 +43,95 @@ def haversine(
         - Default: 1
 
     """
-    try:
-        # convert decimal degrees to radians
-        lon1, lat1, lon2, lat2 = map(
-            math.radians,
-            [
-                origin[1],
-                origin[0],
-                destination[1],
-                destination[0],
-            ],
-        )
-        # haversine formula
-        dlon = lon2 - lon1
-        dlat = lat2 - lat1
-        a = (
-            math.sin(dlat / 2) ** 2
-            + math.cos(lat1) * math.cos(lat2) * math.sin(dlon / 2) ** 2
-        )
-        c = 2 * math.asin(a**0.5)
-        # Set the radius of earth based on the units specified
-        if units == "km":
-            radius = 6371
-        elif units == "m":
-            radius = 6371000
-        elif units == "mi":
-            radius = 3959
-        elif units == "ft":
-            radius = 3959 * 5280
-        else:
-            raise ValueError('Units must be one of "km", "m", "mi", or "ft"')
-        return c * radius * circuity
-    except:
-        print(origin, destination)
-        raise Exception()
+    # convert decimal degrees to radians
+    lon1, lat1, lon2, lat2 = map(
+        math.radians,
+        [
+            origin[1],
+            origin[0],
+            destination[1],
+            destination[0],
+        ],
+    )
+    # haversine formula
+    dlon = lon2 - lon1
+    dlat = lat2 - lat1
+    a = (
+        math.sin(dlat / 2) ** 2
+        + math.cos(lat1) * math.cos(lat2) * math.sin(dlon / 2) ** 2
+    )
+    c = 2 * math.asin(a**0.5)
+    # Set the radius of earth based on the units specified
+    radius = earth_radius.get(
+        units, 6371
+    )  # Default to kilometers if not specified or invalid
+    return c * radius * circuity
+
+
+def cheap_ruler(origin, destination, units="km", circuity=1):
+    """
+    Function:
+
+    Calculates a fast approximate distance between two lat/lon points using Mapbox's "cheap ruler" method.
+
+    Note: In general, this method is considered faster than the haversine formula, but less accurate, especially near the poles and for long distances.
+    For this implementation, it tests slower than haversine, but it seems like there might be some room for optimization.
+
+    Required Arguments
+    - `origin`
+        - Type: list of two floats | ints
+        - What: The origin point as a list of "latitude" and "longitude"
+    - `destination`
+        - Type: list of two floats | ints
+        - What: The destination point as a list of "latitude" and "longitude"
+
+    Optional Arguments
+
+    - `units`
+        - Type: str
+        - What: units to return the distance in? (one of "km", "m", "mi", or "ft")
+        - Default: "km"
+        origin: [lat, lon] in degrees
+        destination: [lat, lon] in degrees
+        units: 'km', 'm', 'mi', or 'ft'
+    - `circuity`
+        - Type: int | float
+        - What: Multiplier to increase the calculated distance (to account for circuity)
+        - Default: 1
+        - Note: Consider using this as less than 1 when you are writing a heuristic function for
+            A* as this method can overestimate distances, especially near the Earth's poles.
+
+    Returns:
+        Distance in the specified units
+    """
+
+    # Constants
+    radius = earth_radius.get(
+        units, 6371
+    )  # Default to kilometers if not specified
+    lat1, lon1 = origin
+    lat2, lon2 = destination
+    # Get the adjusted longitude difference
+    lon_diff = abs(lon2 - lon1)
+    lon_diff = min(360 - lon_diff, lon_diff)
+
+    # Midpoint latitude in radians
+    mid_lat = (lat1 + lat2) / 2 * radians_per_degree
+    cos_lat = math.cos(mid_lat)
+
+    # Radius adjustments
+    w_squared = 1 / (1 - cheap_e2 * (1 - cos_lat**2))
+    w = w_squared**0.5
+
+    # Meters per degree at this latitude (scaled for km)
+    m = radians_per_degree * radius
+    kx = m * w * cos_lat
+    ky = m * w * w_squared * (1 - cheap_e2)
+
+    dx = (lon_diff) * kx
+    dy = (lat2 - lat1) * ky
+
+    return (dx**2 + dy**2) ** 0.5 * circuity
 
 
 def hard_round(decimal_places: int, a: [float | int]):

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scgraph
-Version: 2.6.0
+Version: 2.7.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
@@ -43,6 +43,9 @@ Low Level: https://connor-makowski.github.io/scgraph/scgraph/core.html
                 - 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)
+                - 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
         - Distances:
             - Uses the [haversine formula](https://en.wikipedia.org/wiki/Haversine_formula) to calculate the distance between two points on earth
@@ -89,7 +92,8 @@ In this case, calculate the shortest maritime path between Shanghai, China and S
 # Use a maritime network geograph
 from scgraph.geographs.marnet import marnet_geograph
 
-# Get the shortest path between
+# Get the shortest maritime path between Shanghai, China and Savannah, Georgia, USA
+# Note: The origin and destination nodes can be any latitude / longitude pair
 output = marnet_geograph.get_shortest_path(
     origin_node={"latitude": 31.23,"longitude": 121.47},
     destination_node={"latitude": 32.08,"longitude": -81.09},
@@ -194,11 +198,16 @@ Using `scgraph_data` geographs:
 - Note: Make sure to install the `scgraph_data` package before using these geographs
 ```py
 from scgraph_data.world_railways import world_railways_geograph
+from scgraph import Graph
 
 # Get the shortest path between Kalamazoo Michigan and Detroit Michigan by Train
 output = world_railways_geograph.get_shortest_path(
     origin_node={"latitude": 42.29,"longitude": -85.58},
-    destination_node={"latitude": 42.33,"longitude": -83.05}
+    destination_node={"latitude": 42.33,"longitude": -83.05},
+    # Optional: Use the A* algorithm
+    algorithm_fn=Graph.a_star,
+    # Optional: Pass the haversine function as the heuristic function to the A* algorithm
+    algorithm_kwargs={"heuristic_fn": world_railways_geograph.haversine},
 )
 ```
 

{scgraph-2.6.0 → scgraph-2.7.0}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = scgraph
-version = 2.6.0
+version = 2.7.0
 description_file = README.md
 
 [options]