scgraph 2.2.0__tar.gz → 2.4.0__tar.gz

{scgraph-2.2.0/scgraph.egg-info → scgraph-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: scgraph
-Version: 2.2.0
+Version: 2.4.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
@@ -9,13 +9,15 @@ Project-URL: Documentation, https://connor-makowski.github.io/scgraph/core.html
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+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,12 +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.6.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
+Make sure you have Python 3.10.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
+
+Note: Support for python3.6-python3.9 is available up to version 2.2.0.
 
 ## Installation
 
@@ -67,7 +73,10 @@ pip install scgraph
 
 ## Use with Google Colab
 
-See the example [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/example.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)
+
 
 # Getting Started
 
@@ -101,7 +110,7 @@ In the above example, the `output` variable is a dictionary with three keys: `le
             - `ft` (feet)
 - `coordinate_path`: A list of lists [`latitude`,`longitude`] that make up the shortest path
 
-For more examples including viewing the output on a map, see the [example notebook](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/example.ipynb).
+For more examples including viewing the output on a map, see the [example notebook](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/getting_started.ipynb).
 
 ## Included GeoGraphs
 
@@ -136,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:
@@ -165,7 +217,7 @@ output = marnet_geograph.get_shortest_path(
 get_line_path(output, filename='output.geojson')
 ```
 
-Modify an existing geograph: See the notebook [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/example_making_modifications.ipynb)
+Modify an existing geograph: See the notebook [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/geograph_modifications.ipynb)
 
 
 You can specify your own custom graphs for direct access to the solving algorithms. This requires the use of the low level `Graph` class
@@ -173,9 +225,9 @@ You can specify your own custom graphs for direct access to the solving algorith
 ```py
 from scgraph import Graph
 
-# Define a graph
+# Define an arbitrary graph
 # See the graph definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
     {1: 5, 2: 1},
     {0: 5, 2: 2, 3: 1},
@@ -200,25 +252,67 @@ from scgraph import GeoGraph
 
 # Define nodes
 # See the nodes definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 nodes = [
-    [0,0],
-    [0,1],
-    [1,0],
-    [1,1],
-    [1,2],
-    [2,1]
+    # London
+    [51.5074, -0.1278],
+    # Paris
+    [48.8566, 2.3522],
+    # Berlin
+    [52.5200, 13.4050],
+    # Rome
+    [41.9028, 12.4964],
+    # Madrid
+    [40.4168, -3.7038],
+    # Lisbon
+    [38.7223, -9.1393]
 ]
 # Define a graph
 # See the graph definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
-    {1: 5, 2: 1},
-    {0: 5, 2: 2, 3: 1},
-    {0: 1, 1: 2, 3: 4, 4: 8},
-    {1: 1, 2: 4, 4: 3, 5: 6},
-    {2: 8, 3: 3},
-    {3: 6}
+    # From London
+    {
+        # To Paris
+        1: 311,
+    },
+    # From Paris
+    {
+        # To London
+        0: 311, 
+        # To Berlin
+        2: 878, 
+        # To Rome
+        3: 1439,
+        # To Madrid
+        4: 1053
+    },
+    # From Berlin
+    {
+        # To Paris 
+        1: 878,
+        # To Rome
+        3: 1181,
+    },
+    # From Rome
+    {
+        # To Paris
+        1: 1439,
+        # To Berlin
+        2: 1181,
+    },
+    # From Madrid
+    {
+        # To Paris
+        1: 1053,
+        # To Lisbon
+        5: 623
+    },
+    # From Lisbon
+    {
+        # To Madrid
+        4: 623
+    }
 ]
 
 # Create a GeoGraph object
@@ -231,24 +325,49 @@ my_geograph.validate_graph()
 my_geograph.validate_nodes()
 
 # Get the shortest path between two points
+# In this case, Birmingham England and Zaragoza Spain
+# Since Birmingham and Zaragoza are not in the graph,
+# the algorithm will add them into the graph.
+# See: https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph.get_shortest_path
+# Expected output would be to go from
+# Birmingham -> London -> Paris -> Madrid -> Zaragoza
+
 output = my_geograph.get_shortest_path(
-    origin_node = {'latitude': 0, 'longitude': 0},
-    destination_node = {'latitude': 2, 'longitude': 1}
+    # Birmingham England
+    origin_node = {'latitude': 52.4862, 'longitude': -1.8904},
+    # Zaragoza Spain
+    destination_node = {'latitude': 41.6488, 'longitude': -0.8891}
 )
-#=>
+print(output)
 # {
-#     "coordinate_path": [
-#         [0,0],
-#         [0,0],
-#         [1,0],
-#         [0,1],
-#         [1,1],
-#         [2,1],
-#         [2,1]
-#     ],
-#     "length": 10
+#     'length': 1799.4323, 
+#     'coordinate_path': [
+#         [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.2.0 → scgraph-2.4.0}/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,12 +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.6.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
+Make sure you have Python 3.10.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
+
+Note: Support for python3.6-python3.9 is available up to version 2.2.0.
 
 ## Installation
 
@@ -52,7 +57,10 @@ pip install scgraph
 
 ## Use with Google Colab
 
-See the example [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/example.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)
+
 
 # Getting Started
 
@@ -86,7 +94,7 @@ In the above example, the `output` variable is a dictionary with three keys: `le
             - `ft` (feet)
 - `coordinate_path`: A list of lists [`latitude`,`longitude`] that make up the shortest path
 
-For more examples including viewing the output on a map, see the [example notebook](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/example.ipynb).
+For more examples including viewing the output on a map, see the [example notebook](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/getting_started.ipynb).
 
 ## Included GeoGraphs
 
@@ -121,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:
@@ -150,7 +201,7 @@ output = marnet_geograph.get_shortest_path(
 get_line_path(output, filename='output.geojson')
 ```
 
-Modify an existing geograph: See the notebook [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/example_making_modifications.ipynb)
+Modify an existing geograph: See the notebook [here](https://colab.research.google.com/github/connor-makowski/scgraph/blob/main/examples/geograph_modifications.ipynb)
 
 
 You can specify your own custom graphs for direct access to the solving algorithms. This requires the use of the low level `Graph` class
@@ -158,9 +209,9 @@ You can specify your own custom graphs for direct access to the solving algorith
 ```py
 from scgraph import Graph
 
-# Define a graph
+# Define an arbitrary graph
 # See the graph definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
     {1: 5, 2: 1},
     {0: 5, 2: 2, 3: 1},
@@ -185,25 +236,67 @@ from scgraph import GeoGraph
 
 # Define nodes
 # See the nodes definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 nodes = [
-    [0,0],
-    [0,1],
-    [1,0],
-    [1,1],
-    [1,2],
-    [2,1]
+    # London
+    [51.5074, -0.1278],
+    # Paris
+    [48.8566, 2.3522],
+    # Berlin
+    [52.5200, 13.4050],
+    # Rome
+    [41.9028, 12.4964],
+    # Madrid
+    [40.4168, -3.7038],
+    # Lisbon
+    [38.7223, -9.1393]
 ]
 # Define a graph
 # See the graph definitions here: 
-# https://connor-makowski.github.io/scgraph/scgraph/core.html
+# https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph
 graph = [
-    {1: 5, 2: 1},
-    {0: 5, 2: 2, 3: 1},
-    {0: 1, 1: 2, 3: 4, 4: 8},
-    {1: 1, 2: 4, 4: 3, 5: 6},
-    {2: 8, 3: 3},
-    {3: 6}
+    # From London
+    {
+        # To Paris
+        1: 311,
+    },
+    # From Paris
+    {
+        # To London
+        0: 311, 
+        # To Berlin
+        2: 878, 
+        # To Rome
+        3: 1439,
+        # To Madrid
+        4: 1053
+    },
+    # From Berlin
+    {
+        # To Paris 
+        1: 878,
+        # To Rome
+        3: 1181,
+    },
+    # From Rome
+    {
+        # To Paris
+        1: 1439,
+        # To Berlin
+        2: 1181,
+    },
+    # From Madrid
+    {
+        # To Paris
+        1: 1053,
+        # To Lisbon
+        5: 623
+    },
+    # From Lisbon
+    {
+        # To Madrid
+        4: 623
+    }
 ]
 
 # Create a GeoGraph object
@@ -216,24 +309,49 @@ my_geograph.validate_graph()
 my_geograph.validate_nodes()
 
 # Get the shortest path between two points
+# In this case, Birmingham England and Zaragoza Spain
+# Since Birmingham and Zaragoza are not in the graph,
+# the algorithm will add them into the graph.
+# See: https://connor-makowski.github.io/scgraph/scgraph/core.html#GeoGraph.get_shortest_path
+# Expected output would be to go from
+# Birmingham -> London -> Paris -> Madrid -> Zaragoza
+
 output = my_geograph.get_shortest_path(
-    origin_node = {'latitude': 0, 'longitude': 0},
-    destination_node = {'latitude': 2, 'longitude': 1}
+    # Birmingham England
+    origin_node = {'latitude': 52.4862, 'longitude': -1.8904},
+    # Zaragoza Spain
+    destination_node = {'latitude': 41.6488, 'longitude': -0.8891}
 )
-#=>
+print(output)
 # {
-#     "coordinate_path": [
-#         [0,0],
-#         [0,0],
-#         [1,0],
-#         [0,1],
-#         [1,1],
-#         [2,1],
-#         [2,1]
-#     ],
-#     "length": 10
+#     'length': 1799.4323, 
+#     'coordinate_path': [
+#         [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.2.0 → scgraph-2.4.0}/pyproject.toml

@@ -12,13 +12,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scgraph"
-version = "2.2.0"
+version = "2.4.0"
 description = "Determine an approximate route between two points on earth."
 authors = [
     {name="Connor Makowski", email="conmak@mit.edu"}
 ]
 readme = "README.md"
-requires-python = ">=3.6"
+requires-python = ">=3.10"
 classifiers = [
     "Programming Language :: Python :: 3",
     'License :: OSI Approved :: MIT License',