scgraph 2.3.0__tar.gz → 2.4.1__tar.gz

{scgraph-2.3.0/scgraph.egg-info → scgraph-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: scgraph
-Version: 2.3.0
+Version: 2.4.1
 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
@@ -12,10 +12,12 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Dynamic: license-file
 
 # scgraph
 [![PyPI version](https://badge.fury.io/py/scgraph.svg)](https://badge.fury.io/py/scgraph)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/scgraph.svg?label=PyPI%20downloads)](https://pypi.org/project/scgraph/)
 
 Supply chain graph package for Python
 
@@ -52,14 +54,16 @@ Low Level: https://connor-makowski.github.io/scgraph/scgraph/core.html
 - Antimeridian support
 - Arbitrary start and end points
 - Arbitrary network data sets
-    
+- Grid based graphs
+- Cached shortest path calculations for very fast repetative calculations to or from the same point in a graph.
+    - Note: Geographs are not yet supported for this feature
 
 
 ## Setup
 
 Make sure you have Python 3.10.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
 
-Support for python3.6-3.9 is available up to version 2.2.0
+Note: Support for python3.6-python3.9 is available up to version 2.2.0.
 
 ## Installation
 
@@ -69,7 +73,7 @@ pip install scgraph
 
 ## Use with Google Colab
 
-- [Getting Started](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/getting_started.ipynb) 
+- [Getting Started](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/getting_started.ipynb)
 - [Creating A Multi Path Geojson](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/multi_path_geojson.ipynb)
 - [Modifying A Geograph](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/geograph_modifications.ipynb)
 
@@ -85,9 +89,9 @@ 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 path between
 output = marnet_geograph.get_shortest_path(
-    origin_node={"latitude": 31.23,"longitude": 121.47}, 
+    origin_node={"latitude": 31.23,"longitude": 121.47},
     destination_node={"latitude": 32.08,"longitude": -81.09},
     output_units='km'
 )
@@ -97,8 +101,8 @@ print('Length: ',output['length']) #=> Length:  19596.4653
 In the above example, the `output` variable is a dictionary with three keys: `length` and `coordinate_path`.
 
 - `length`: The distance between the passed origin and destination when traversing the graph along the shortest path
-    - Notes: 
-        - This will be in the units specified by the `output_units` parameter. 
+    - Notes:
+        - This will be in the units specified by the `output_units` parameter.
         - `output_units` options:
             - `km` (kilometers - default)
             - `m` (meters)
@@ -141,6 +145,49 @@ For more examples including viewing the output on a map, see the [example notebo
     - Use: `from scgraph_data.world_highways import world_highways_geograph`
     - See: [scgraph_data](https://github.com/connor-makowski/scgraph_data) for more information and all available geographs.
 
+## GridGraph usage
+
+Example:
+- Create a grid of 20x100 cells.
+    - This creates a grid based graph with connections to all 8 neighbors for each grid item.
+    - Each grid item has 4 cardinal connections at length 1 and 4 diagonal connections at length sqrt(2)
+- Create a wall from (10,5) to (10,99).
+    - This would foce any path to go to the bottom of the graph to get around the wall.
+- Get the shortest path between (2,10) and (18,10)
+    - Note: The length of this path should be 16 without the wall and 20.9704 with the wall.
+
+```py
+from scgraph import GridGraph
+
+x_size = 20
+y_size = 20
+blocks = [(10, i) for i in range(5, y_size)]
+
+# Create the GridGraph object
+gridGraph = GridGraph(
+    x_size=x_size,
+    y_size=y_size,
+    blocks=blocks,
+    add_exterior_walls=True,
+)
+
+# Solve the shortest path between two points
+output = gridGraph.get_shortest_path(
+    origin_node={"x": 2, "y": 10},
+    destination_node={"x": 18, "y": 10},
+    # Optional: Specify the output coodinate format (default is 'list_of_dicts)
+    output_coordinate_path="list_of_lists",
+    # Optional: Cache the origin point spanning_tree for faster calculations on future calls
+    cache=True,
+    # Optional: Specify the node to cache the spanning tree for (default is the origin node)
+    # Note: This first call will be slower, but future calls using this origin node will be substantially faster
+    cache_for="origin",
+)
+
+print(output)
+#=> {'length': 20.9704, 'coordinate_path': [[2, 10], [3, 9], [4, 8], [5, 8], [6, 7], [7, 6], [8, 5], [9, 4], [10, 4], [11, 4], [12, 5], [13, 6], [14, 7], [15, 7], [16, 8], [17, 9], [18, 10]]}
+```
+
 ## Advanced Usage
 
 Using `scgraph_data` geographs:
@@ -150,7 +197,7 @@ from scgraph_data.world_railways import world_railways_geograph
 
 # 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}, 
+    origin_node={"latitude": 42.29,"longitude": -85.58},
     destination_node={"latitude": 42.33,"longitude": -83.05}
 )
 ```
@@ -163,7 +210,7 @@ from scgraph.utils import get_line_path
 
  # Get the shortest sea path between Sri Lanka and Somalia
 output = marnet_geograph.get_shortest_path(
-    origin_node={"latitude": 7.87,"longitude": 80.77}, 
+    origin_node={"latitude": 7.87,"longitude": 80.77},
     destination_node={"latitude": 5.15,"longitude": 46.20}
 )
 # Write the output to a geojson file
@@ -179,7 +226,7 @@ You can specify your own custom graphs for direct access to the solving algorith
 from scgraph import Graph
 
 # Define an arbitrary graph
-# See the graph definitions here: 
+# See the graph definitions here:
 # https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
     {1: 5, 2: 1},
@@ -204,7 +251,7 @@ You can also use a slightly higher level `GeoGraph` class to work with latitude
 from scgraph import GeoGraph
 
 # Define nodes
-# See the nodes definitions here: 
+# See the nodes definitions here:
 # https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 nodes = [
     # London
@@ -221,7 +268,7 @@ nodes = [
     [38.7223, -9.1393]
 ]
 # Define a graph
-# See the graph definitions here: 
+# See the graph definitions here:
 # https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
     # From London
@@ -232,9 +279,9 @@ graph = [
     # From Paris
     {
         # To London
-        0: 311, 
+        0: 311,
         # To Berlin
-        2: 878, 
+        2: 878,
         # To Rome
         3: 1439,
         # To Madrid
@@ -242,7 +289,7 @@ graph = [
     },
     # From Berlin
     {
-        # To Paris 
+        # To Paris
         1: 878,
         # To Rome
         3: 1181,
@@ -293,17 +340,34 @@ output = my_geograph.get_shortest_path(
 )
 print(output)
 # {
-#     'length': 1799.4323, 
+#     'length': 1799.4323,
 #     'coordinate_path': [
-#         [52.4862, -1.8904], 
-#         [51.5074, -0.1278], 
-#         [48.8566, 2.3522], 
-#         [40.4168, -3.7038], 
+#         [52.4862, -1.8904],
+#         [51.5074, -0.1278],
+#         [48.8566, 2.3522],
+#         [40.4168, -3.7038],
 #         [41.6488, -0.8891]
 #     ]
 # }
 
 ```
 
+# Development
+## Running Tests, Prettifying Code, and Updating Docs
+
+Make sure Docker is installed and running on a Unix system (Linux, MacOS, WSL2).
+
+- Create a docker container and drop into a shell
+    - `./run.sh`
+- Run all tests (see ./utils/test.sh)
+    - `./run.sh test`
+- Prettify the code (see ./utils/prettify.sh)
+    - `./run.sh prettify`
+- Update the docs (see ./utils/docs.sh)
+    - `./run.sh docs`
+
+- Note: You can and should modify the `Dockerfile` to test different python versions.
+
+
 ## 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.

{scgraph-2.3.0 → scgraph-2.4.1}/README.md

@@ -1,6 +1,7 @@
 # scgraph
 [![PyPI version](https://badge.fury.io/py/scgraph.svg)](https://badge.fury.io/py/scgraph)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/scgraph.svg?label=PyPI%20downloads)](https://pypi.org/project/scgraph/)
 
 Supply chain graph package for Python
 
@@ -37,14 +38,16 @@ Low Level: https://connor-makowski.github.io/scgraph/scgraph/core.html
 - Antimeridian support
 - Arbitrary start and end points
 - Arbitrary network data sets
-    
+- Grid based graphs
+- Cached shortest path calculations for very fast repetative calculations to or from the same point in a graph.
+    - Note: Geographs are not yet supported for this feature
 
 
 ## Setup
 
 Make sure you have Python 3.10.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
 
-Support for python3.6-3.9 is available up to version 2.2.0
+Note: Support for python3.6-python3.9 is available up to version 2.2.0.
 
 ## Installation
 
@@ -54,7 +57,7 @@ pip install scgraph
 
 ## Use with Google Colab
 
-- [Getting Started](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/getting_started.ipynb) 
+- [Getting Started](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/getting_started.ipynb)
 - [Creating A Multi Path Geojson](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/multi_path_geojson.ipynb)
 - [Modifying A Geograph](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/geograph_modifications.ipynb)
 
@@ -70,9 +73,9 @@ 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 path between
 output = marnet_geograph.get_shortest_path(
-    origin_node={"latitude": 31.23,"longitude": 121.47}, 
+    origin_node={"latitude": 31.23,"longitude": 121.47},
     destination_node={"latitude": 32.08,"longitude": -81.09},
     output_units='km'
 )
@@ -82,8 +85,8 @@ print('Length: ',output['length']) #=> Length:  19596.4653
 In the above example, the `output` variable is a dictionary with three keys: `length` and `coordinate_path`.
 
 - `length`: The distance between the passed origin and destination when traversing the graph along the shortest path
-    - Notes: 
-        - This will be in the units specified by the `output_units` parameter. 
+    - Notes:
+        - This will be in the units specified by the `output_units` parameter.
         - `output_units` options:
             - `km` (kilometers - default)
             - `m` (meters)
@@ -126,6 +129,49 @@ For more examples including viewing the output on a map, see the [example notebo
     - Use: `from scgraph_data.world_highways import world_highways_geograph`
     - See: [scgraph_data](https://github.com/connor-makowski/scgraph_data) for more information and all available geographs.
 
+## GridGraph usage
+
+Example:
+- Create a grid of 20x100 cells.
+    - This creates a grid based graph with connections to all 8 neighbors for each grid item.
+    - Each grid item has 4 cardinal connections at length 1 and 4 diagonal connections at length sqrt(2)
+- Create a wall from (10,5) to (10,99).
+    - This would foce any path to go to the bottom of the graph to get around the wall.
+- Get the shortest path between (2,10) and (18,10)
+    - Note: The length of this path should be 16 without the wall and 20.9704 with the wall.
+
+```py
+from scgraph import GridGraph
+
+x_size = 20
+y_size = 20
+blocks = [(10, i) for i in range(5, y_size)]
+
+# Create the GridGraph object
+gridGraph = GridGraph(
+    x_size=x_size,
+    y_size=y_size,
+    blocks=blocks,
+    add_exterior_walls=True,
+)
+
+# Solve the shortest path between two points
+output = gridGraph.get_shortest_path(
+    origin_node={"x": 2, "y": 10},
+    destination_node={"x": 18, "y": 10},
+    # Optional: Specify the output coodinate format (default is 'list_of_dicts)
+    output_coordinate_path="list_of_lists",
+    # Optional: Cache the origin point spanning_tree for faster calculations on future calls
+    cache=True,
+    # Optional: Specify the node to cache the spanning tree for (default is the origin node)
+    # Note: This first call will be slower, but future calls using this origin node will be substantially faster
+    cache_for="origin",
+)
+
+print(output)
+#=> {'length': 20.9704, 'coordinate_path': [[2, 10], [3, 9], [4, 8], [5, 8], [6, 7], [7, 6], [8, 5], [9, 4], [10, 4], [11, 4], [12, 5], [13, 6], [14, 7], [15, 7], [16, 8], [17, 9], [18, 10]]}
+```
+
 ## Advanced Usage
 
 Using `scgraph_data` geographs:
@@ -135,7 +181,7 @@ from scgraph_data.world_railways import world_railways_geograph
 
 # 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}, 
+    origin_node={"latitude": 42.29,"longitude": -85.58},
     destination_node={"latitude": 42.33,"longitude": -83.05}
 )
 ```
@@ -148,7 +194,7 @@ from scgraph.utils import get_line_path
 
  # Get the shortest sea path between Sri Lanka and Somalia
 output = marnet_geograph.get_shortest_path(
-    origin_node={"latitude": 7.87,"longitude": 80.77}, 
+    origin_node={"latitude": 7.87,"longitude": 80.77},
     destination_node={"latitude": 5.15,"longitude": 46.20}
 )
 # Write the output to a geojson file
@@ -164,7 +210,7 @@ You can specify your own custom graphs for direct access to the solving algorith
 from scgraph import Graph
 
 # Define an arbitrary graph
-# See the graph definitions here: 
+# See the graph definitions here:
 # https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
     {1: 5, 2: 1},
@@ -189,7 +235,7 @@ You can also use a slightly higher level `GeoGraph` class to work with latitude
 from scgraph import GeoGraph
 
 # Define nodes
-# See the nodes definitions here: 
+# See the nodes definitions here:
 # https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 nodes = [
     # London
@@ -206,7 +252,7 @@ nodes = [
     [38.7223, -9.1393]
 ]
 # Define a graph
-# See the graph definitions here: 
+# See the graph definitions here:
 # https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
     # From London
@@ -217,9 +263,9 @@ graph = [
     # From Paris
     {
         # To London
-        0: 311, 
+        0: 311,
         # To Berlin
-        2: 878, 
+        2: 878,
         # To Rome
         3: 1439,
         # To Madrid
@@ -227,7 +273,7 @@ graph = [
     },
     # From Berlin
     {
-        # To Paris 
+        # To Paris
         1: 878,
         # To Rome
         3: 1181,
@@ -278,17 +324,34 @@ output = my_geograph.get_shortest_path(
 )
 print(output)
 # {
-#     'length': 1799.4323, 
+#     'length': 1799.4323,
 #     'coordinate_path': [
-#         [52.4862, -1.8904], 
-#         [51.5074, -0.1278], 
-#         [48.8566, 2.3522], 
-#         [40.4168, -3.7038], 
+#         [52.4862, -1.8904],
+#         [51.5074, -0.1278],
+#         [48.8566, 2.3522],
+#         [40.4168, -3.7038],
 #         [41.6488, -0.8891]
 #     ]
 # }
 
 ```
 
+# Development
+## Running Tests, Prettifying Code, and Updating Docs
+
+Make sure Docker is installed and running on a Unix system (Linux, MacOS, WSL2).
+
+- Create a docker container and drop into a shell
+    - `./run.sh`
+- Run all tests (see ./utils/test.sh)
+    - `./run.sh test`
+- Prettify the code (see ./utils/prettify.sh)
+    - `./run.sh prettify`
+- Update the docs (see ./utils/docs.sh)
+    - `./run.sh docs`
+
+- Note: You can and should modify the `Dockerfile` to test different python versions.
+
+
 ## 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.

{scgraph-2.3.0 → scgraph-2.4.1}/pyproject.toml

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