Docs updates+route to graph

.gitignore

@@ -39,4 +39,7 @@ dist/
 *.parquet
 *.dill
 
+# web docs
+site/
+
 

docs/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Tobias Karusseit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

docs/NOTICE.md

@@ -0,0 +1,44 @@
+# Dependencies and Licenses
+
+This project `MultiModalRouter` depends on the following libraries. All licenses are permissive and compatible with MIT licensing for this project.  
+
+| Package | Version | License | License Link |
+|---------|---------|---------|--------------|
+| colorama | >=0.4.6 | BSD 3-Clause | [License](https://github.com/tartley/colorama/blob/master/LICENSE) |
+| dill | >=0.4.0 | BSD | [License](https://github.com/uqfoundation/dill/blob/main/LICENSE) |
+| filelock | >=3.19.1 | MIT | [License](https://github.com/tox-dev/py-filelock/blob/main/LICENSE) |
+| fsspec | >=2025.9.0 | Apache 2.0 | [License](https://github.com/fsspec/filesystem_spec/blob/main/LICENSE) |
+| Jinja2 | >=3.1.6 | BSD-3-Clause | [License](https://github.com/pallets/jinja/blob/main/LICENSE) |
+| MarkupSafe | >=3.0.2 | BSD-3-Clause | [License](https://github.com/pallets/markupsafe/blob/main/LICENSE) |
+| mpmath | >=1.3.0 | BSD | [License](https://github.com/fredrik-johansson/mpmath/blob/master/LICENSE) |
+| networkx | >=3.5 | BSD | [License](https://github.com/networkx/networkx/blob/main/LICENSE.txt) |
+| numpy | >=2.3.3 | BSD | [License](https://github.com/numpy/numpy/blob/main/LICENSE.txt) |
+| pandas | >=2.3.2 | BSD-3-Clause | [License](https://github.com/pandas-dev/pandas/blob/main/LICENSE) |
+| parquet | >=1.3.1 | Apache 2.0 | [License](https://github.com/urschrei/parquet-python/blob/master/LICENSE) |
+| ply | >=3.11 | BSD | [License](https://github.com/dabeaz/ply/blob/master/LICENSE.txt) |
+| pyarrow | >=21.0.0 | Apache 2.0 | [License](https://github.com/apache/arrow/blob/master/LICENSE) |
+| python-dateutil | >=2.9.0.post0 | BSD | [License](https://github.com/dateutil/dateutil/blob/master/LICENSE.txt) |
+| pytz | >=2025.2 | MIT | [License](https://github.com/stub42/pytz/blob/master/LICENSE) |
+| setuptools | >=80.9.0 | MIT | [License](https://github.com/pypa/setuptools/blob/main/LICENSE) |
+| six | >=1.17.0 | MIT | [License](https://github.com/benjaminp/six/blob/master/LICENSE) |
+| sympy | >=1.14.0 | BSD | [License](https://github.com/sympy/sympy/blob/master/LICENSE) |
+| thriftpy2 | >=0.5.3 | MIT | [License](https://github.com/Thriftpy/thriftpy2/blob/master/LICENSE) |
+| tqdm | >=4.67.1 | MPL 2.0 | [License](https://github.com/tqdm/tqdm/blob/master/LICENSE) |
+| typing_extensions | >=4.15.0 | PSF | [License](https://github.com/python/typing_extensions/blob/main/LICENSE) |
+| tzdata | >=2025.2 | Public Domain | [License](https://github.com/python/tzdata) |
+
+## Optional Dependencies
+
+| Package | Version | License | License Link |
+|---------|---------|---------|--------------|
+| torch | >=2.8.0 | BSD | [License](https://github.com/pytorch/pytorch/blob/master/LICENSE) |
+| plotly | >=6.3.0 | MIT | [License](https://github.com/plotly/plotly.py/blob/master/LICENSE) |
+| pytest | >=8.0 | MIT | [License](https://github.com/pytest-dev/pytest/blob/main/LICENSE) |
+
+---
+
+### Notes
+
+1. All packages listed above are permissively licensed (MIT, BSD, Apache 2.0, or Public Domain), so they are compatible with MIT licensing for this project.  
+2. If distributing this library, include this `DEPENDENCIES.md` file and your own MIT license file to give proper attribution.  
+3. Optional dependencies should be listed in documentation or `pyproject.toml` extras.  

docs/cli.md

@@ -1,4 +1,4 @@
-[HOME](../README.md)
+[HOME](./index.md)
 
 # command line interface
 
@@ -22,7 +22,7 @@ multimodalrouter-build hubType1 transportMode1 pathToDataset1 --maxDist 123 --ex
     - NOTE: you can add as many hub types and datasets at once as you want just make sure the order is always; type1 mode1 path1 type2 ...
 - `--maxDist` = the float value that limits the maximum length a driving edge can have (this is irrelevant id `--enableDriving` isn't set)
 - `extraMetrics` = a list of keys that the graph will scan your data for and add the values to any edge where the key exists in the data (NOTE: each key should be present in at least one dataset, the number of extra metrics is not limited)
-- `--drivingEnabled` = if this flag is added the graph will try to build connections between hubs for any hub that is closer than the `--maxDist` to anoter hub (check [here](../README.md#important-considerations-for-your-usecase) to see if your data allows this)
+- `--drivingEnabled` = if this flag is added the graph will try to build connections between hubs for any hub that is closer than the `--maxDist` to anoter hub (check [here](./index.md#important-considerations-for-your-usecase) to see if your data allows this)
 - `--Dir` = put the target directory of the save file here. (if this is not set the graph will be saved to a default dir)
 
 ### example

docs/graph.md

@@ -1,4 +1,4 @@
-[HOME](../README.md)
+[HOME](./index.md)
 
 [graph](#routegraph)
 
@@ -576,8 +576,24 @@ Start: GOM
 -> NBO
         Edge: (transportMode=plane, metrics={'distance': 515.1466233682448})
 -> LOK
+``` 
+
+#### Route To Graph
+
+```python
+def asGraph(self, graph):
 ```
 
+#### args:
+
+* graph: [RouteGraph](#routegraph) = The graph instance that created this route
+
+#### returns:
+
+* [RouteGraph](#routegraph) = a graph with only the nodes from the route
+
+**NOTES** if the given graph is missing some hubs from the route the created graph will skip the missing hubs and include new edges to connect the present hubs. (The new edges will only include the `distance` metric, which is calculated by the passed graph's distance function)
+
 ### Filter 
 
 The `Filter` class is an abstract class you can implement to add custom filter to you searches

docs/index.md

@@ -0,0 +1,75 @@
+# Multi Modal Router
+
+The Multi Modal Router is a graph-based routing engine that allows you to build and query any hub-based network. It supports multiple transport modes like driving, flying, or shipping, and lets you optimize routes by distance, time, or custom metrics. It can be expanded to any n-dimensional space making it versatile in any coordinate space
+
+> NOTE: This project is a work in progress and features might be added and or changed
+
+# In depth Documentation
+
+[installation guide](./installation.md)
+
+[graph module documentation](./graph.md)
+
+[command line interface documentation](./cli.md)
+
+[utilities documentation](./utils.md)
+
+code example can be found in `docs/examples/`
+
+# Features
+
+## Building Freedom / Unlimited Usecases
+
+The graph can be build from any data aslong as the required fields are present ([example](./examples/demoData.csv)). Whether your data contains real world places or you are working in a more abstract spaces with special coordinates and distance metrics the graph will behave the same (with minor limitations due to dynamic distance calculation, but not a problem when distances are already precomputed. [solutions](./graph.md#advanced-options)).
+
+#### Example Usecases
+
+- real world flight router
+    - uses data with real flight data and actuall airport coordinates
+    - builds a graph with `airport` [Hubs](./graph.md#hub)
+    - connects `airports` based on flight routes
+    - `finds` the `shortest flights` or `multi leg routes` to get from `A` to `B`
+    - simple example implementation [here](./examples/flightRouter/main.py)
+
+- social relation ship graph
+    - uses user data like a social network where users are connected through others via a group of other users
+    - builds a graph with `users` as Hubs
+    - connects users based on know interactions or any other connection meric
+    - `finds` users that are likely to `share`; `interests`, `friends`, `a social circle`, etc.
+
+- coordinate based game AI and pathfinding
+    - uses a predefined path network (e.g. a simple maze)
+    - `builds` the garph representation of the network
+    - `finds` the shortest way to get from any point `A` to any other point `B` in the network
+    - you can checkout a simple example implementation for a maze pathfinder [here](./examples/mazePathfinder/main.py)
+
+![example from the maze solver](./solvedMaze1.png)
+
+## graph visualizations
+
+Use the build-in [visualization](./visualization.md) tool to plot any `2D` or `3D` Graph.
+
+![example plot of flight paths](./FlightPathPlot.png)
+
+## Important considerations for your usecase
+
+Depending on your usecase and datasets some features may not be usable see solutions below
+
+### potential problems based on use case
+
+**Please check your data for the following**
+
+| distance present | coordinate format | unusable features | special considerations |
+|------------------|-------------------|-------------------|------------------------|
+|      YES         |      degrees      |      None         |        None|
+|      YES|not degrees| runtime distance calculations| set [drivingEnabled = False](./graph.md#args) or do [this](./graph.md#swap-distance-method)|
+| NO | degrees | None | distances must be calculated when preprocessing |
+| NO | not degrees | **ALL** | **You can't build the graph with neither distances or supported coordinates!** [**SOLUTION**](./graph.md#swap-distance-method)
+
+[**example dataframe with the required fields**](./examples/demoData.csv)
+
+[LICENSE](./LICENSE.md)
+
+[dependencies](./NOTICE.md)
+
+

docs/installation.md

@@ -1,4 +1,4 @@
-[HOME](../README.md)
+[HOME](./index.md)
 
 # Installation Guide
 
@@ -7,7 +7,7 @@
 First check if your data comes with precomputed distances and if you are going to want to use the default [driving connections](./graph.md) when building your graph.
 Depending on your choices you will need to install the library with torch. To see what your use case requires check the table below and copy the command.
 
-| data has distances | use driving edges | planning to use build-in [Haversine distance](../src/multimodalrouter/graph/graph.py) | installation mode                   |
+| data has distances | use driving edges | planning to use build-in Haversine distance | installation mode                   |
 |--------------------|-------------------|---------------------------------------------|-------------------------------------|
 |       YES          |        YES        | / |`pip install multimodalrouter[torch]`|
 |       YES          |        NO         | / |`pip install multimodalrouter[torch]`|

docs/utils.md

@@ -1 +1 @@
-[HOME](../README.md)
+[HOME](./index.md)

docs/visualization.md

@@ -1,4 +1,4 @@
-[HOME](../README.md)
+[HOME](./index.md)
 
 # Graph Plotting
 

mkdocs.yml

@@ -0,0 +1,17 @@
+site_name: Multi Modal Router Documentation
+site_url: https://mydomain.org/multimodalrouter-docs
+theme:
+  name: material
+nav:
+  - Home: index.md
+  - Installation Guide: installation.md
+  - Graph: graph.md
+  - Visualization: visualization.md
+  - Command Line Interface: cli.md
+  - Utils: utils.md
+  - License: LICENSE.md
+  - Notice: NOTICE.md
+markdown_extensions:
+  - pymdownx.arithmatex
+
+

src/multimodalrouter/graph/dataclasses.py

@@ -65,6 +65,15 @@ def getMetric(self, mode: str, dest_id: str, metric: str) -> float:
         connection = self.outgoing.get(mode, {}).get(dest_id)
         return getattr(connection, metric, None) if connection else None
 
+    def clone(self) -> "Hub":
+        new = Hub(self.coords[:], self.id, self.hubType)
+
+        for mode, dests in self.outgoing.items():
+            for dest_id, meta in dests.items():
+                new.addOutgoing(mode, dest_id, meta.copy())
+
+        return new
+
     def __hash__(self):
         return hash((self.hubType, self.id))
 
@@ -101,6 +110,56 @@ def flatPath(self, toStr=True):
                 pathStr += f"{edge[0]} -> {edge[1]}"
         return pathStr
 
+    def asGraph(self, graph):
+        """
+        Creates a new RouteGraph with only the hubs in the route.
+        It replicates the settings from the original graph.
+
+        ### NOTE:
+            * the graph in the argument should be the same as the graph from which the route was created.
+            * hubs that are present in the route, but not found in the graph will be skipped
+
+        :param:
+            graph: the graph to replicate settings from
+
+        :returns:
+            a new RouteGraph with the specified settings and the added route
+        """
+        from . import RouteGraph
+        subGraph = RouteGraph(
+            maxDistance=graph.maxDrivingDistance,
+            transportModes=graph.TransportModes,
+            compressed=graph.compressed,
+            extraMetricsKeys=graph.extraMetricsKeys,
+            drivingEnabled=graph.drivingEnabled,
+            sourceCoordKeys=graph.sourceCoordKeys,
+            destCoordKeys=graph.destCoordKeys
+        )
+        # gets the hubs from the route (if not present in graph the hub will be dropped)
+        hubs: list[Hub] = [graph.getHubById(edge[0]) for edge in self.path if graph.getHubById(edge[0])]
+
+        copies = [hub.clone() for hub in hubs]
+
+        # add all hubs to subGraph
+        for hub in copies:
+            subGraph.addHub(hub)
+
+        # add links between consecutive hubs
+        for prev, curr in zip(copies, copies[1:]):
+            transpMode = graph.TransportModes[prev.hubType]
+
+            meta = prev.getMetrics(transpMode, curr.id)
+            if meta is None:
+                # recompute distance
+                distance = graph._hubToHubDistances([curr], [prev])[0][0].item()
+                meta = EdgeMetadata(transportMode=transpMode, distance=distance)
+            else:
+                meta = meta.copy()
+
+            subGraph._addLink(prev, curr, transpMode, **meta.metrics)
+
+        return subGraph
+
 
 @dataclass
 class VerboseRoute(Route):

src/multimodalrouter/graph/graph.py

@@ -9,7 +9,7 @@
 import heapq
 import os
 import pandas as pd
-from .dataclasses import Hub, EdgeMetadata, OptimizationMetric, Route, Filter
+from .dataclasses import Hub, EdgeMetadata, OptimizationMetric, Route, Filter, VerboseRoute
 from threading import Lock
 from collections import deque
 
@@ -377,7 +377,7 @@ def find_shortest_path(
         max_segments: int = 10,
         verbose: bool = False,
         custom_filter: Filter = None,
-    ) -> Route | None:
+    ) -> Route | VerboseRoute | None:
         """
         Find the optimal path between two hubs using Dijkstra