multimodalrouter 0.1.3__tar.gz → 0.1.4__tar.gz

{multimodalrouter-0.1.3/src/multiModalRouter.egg-info → multimodalrouter-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multimodalrouter
-Version: 0.1.3
+Version: 0.1.4
 Summary: A graph-based routing library for dynamic routing.
 Author-email: Tobias Karusseit <karusseittobi@gmail.com>
 License: MIT License
@@ -51,6 +51,8 @@ Dynamic: license-file
 
 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
 
+> NEWS: v0.1.3 now on pypi ([installation guide](./docs/installation.md))
+
 > NOTE: This project is a work in progress and features might be added and or changed
 
 # In depth Documentation

{multimodalrouter-0.1.3 → multimodalrouter-0.1.4}/README.md

@@ -2,6 +2,8 @@
 
 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
 
+> NEWS: v0.1.3 now on pypi ([installation guide](./docs/installation.md))
+
 > NOTE: This project is a work in progress and features might be added and or changed
 
 # In depth Documentation

{multimodalrouter-0.1.3 → multimodalrouter-0.1.4}/docs/graph.md

@@ -146,6 +146,31 @@ def find_shortest_path(
 
 **returns** : [Route](#route) or None if no route was found
 
+### radial search /finding all hubs inside a radius
+
+> Note: this doesn't search a direct radius but rather a reachablity distance (e.g.: A and B may have a distance $x \leq r$, but the shortest connecting path has distance $y \geq r$)
+
+```python
+def radial_search(
+    self,
+    hub_id: str,
+    radius: float,
+    optimization_metric: OptimizationMetric | str = OptimizationMetric.DISTANCE,
+    allowed_modes: list[str] = None,
+    custom_filter: Filter = None
+) -> list[float, Hub]:
+```
+
+#### args
+
+- `hub_id`: str = the id of the center hub the search starts at
+- `radius`: float = the maximum value the search metric is allowed to have from the start
+- `optimization_metric`: str = the target metric you want to use for the distance (default='distance')
+- `allowed_modes`: list[str] = the types of edges that are considered (default= None => all edges are checked)
+- `custom_filter`: Filter = a [filter](#filter) object you can pass to add filters for Hubs and edgeMetadata
+
+**returns:** list[ tuple[float, [Hub](#hub)] ] = a list of all reachable hubs with the 'distance' to the start
+
 ### save
 
 ```python
@@ -359,7 +384,51 @@ nDimGraph = RouteGraph(
 
 > It is theoretically possible to combine hubs from differnt dimensions as long as a distance metric is given or the distance is pre calculated
 
+#### custom filters in searches
+
+To add custom rulesets to searches like [`find_shortest_path`](#routing--finding-the-shortest-path-form-a-to-b) you can add your own [`Filter`](#filter) objects
+
+#### example
+
+Imagine one of your datasets has the following keys
+
+```csv
+source, destination, distance, cost, sx, sy, dx, dy, namex, namey
+```
+
+You have now build your graph with the extra keys: `cost`, `namex`,`namey`, and you want to start a shortest path search that excludes edges where `cost` > `C` and the where the destination `namey` = `N`. Additionally you want to exclude a list of `hub Ids` = `I`
+
+**create Filter:**
+
+```python
+from multimodalrouter import Filter
+
+class CustomFilter(Filter):
+
+    def __init__(self, C: float, N: str, I: list[str]):
+        self.C = C
+        self.N = N
+        self.I = I
+
+    def filterHub(self, hub: Hub):
+        return hub.id not in self.I
+
+    def filterEdge(self, edge: EdgeMetadata):
+        return (edge.getMetric('cost') < self.C 
+                and egde-getMetric('namey') != self.N
+               )
+```
+
+**use filter**
+
+```python
+# graph creation code here
 
+route = graph.find_shortest_path(
+    **kwargs,
+    custom_filter=CustomFilter(c, n, i) # your filter instance
+)
+```
 ---
 ---
 ---
@@ -509,6 +578,45 @@ Start: GOM
 -> LOK
 ```
 
+### Filter 
+
+The `Filter` class is an abstract class you can implement to add custom filter to you searches
+
+#### example
+
+```python
+class ExampleFilter(Filter):
+
+    def __init__(
+        self, 
+        forbiddenHubs: list[str], 
+        filterVal: str | float
+    ):
+        self.forbiddenHubs = forbiddenHubs
+        self.filterVal = filterVal
+
+    def filterHub(self, hub: Hub) -> bool:
+        return hub.id not in self.forbiddenHubs
+
+    def filterEdge(self, edge: EdgeMetadata) -> bool:
+        return edge.getMetric('distance') < 3 and edge.getMetric('yourCustomMetric') != self.filterVal
+```
+
+This `ExampleFilter` will remove all hubs with Ids in the forbidden hubs list and ignore all edges where: $distance > 3 \lor customMetric = filterVal $
+
+To make your own `Filter` just implement the ``__init__``, `filterHUb` & `filterEdge` functions and pass an object to the search (custom_filter = your flter object)
+
+> Tipp: if you want to only add a filter for either Hubs or Edges set the function that shouldn't filter to return `True`
+
+**example**
+```python
+def filterHub(self, hub: Hub) -> bool:
+    return True
+```
+
+will let any hub pass through the filter
+
+
 
 
 

{multimodalrouter-0.1.3 → multimodalrouter-0.1.4}/docs/installation.md

@@ -7,12 +7,15 @@
 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 | installation mode                   |
-|--------------------|-------------------|-------------------------------------|
-|       YES          |        YES        |`pip install .[torch]`|
-|       YES          |        NO         |`pip install .[torch]`|
-|       NO           |        YES        |`pip install .[torch]`|
-|       NO           |        NO         |   `pip install .`    |
+| data has distances | use driving edges | planning to use build-in [Haversine distance](../src/multimodalrouter/graph/graph.py) | installation mode                   |
+|--------------------|-------------------|---------------------------------------------|-------------------------------------|
+|       YES          |        YES        | / |`pip install multimodalrouter[torch]`|
+|       YES          |        NO         | / |`pip install multimodalrouter[torch]`|
+|       NO           |        YES        | / |`pip install multimodalrouter[torch]`|
+|       NO           |        NO         | NO |  `pip install multimodalrouter`    |
+| / | / | YES | `pip install multimodalrouter[torch]`
+
+> Tip: if unsure whether you will need torch or not, install without it first and install torch later if necessary
 
 ## Step 2
 

{multimodalrouter-0.1.3 → multimodalrouter-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "multimodalrouter"
-version = "0.1.3"
+version = "0.1.4"
 description = "A graph-based routing library for dynamic routing."
 readme = "README.md"
 license = { file = "LICENSE.md" }

{multimodalrouter-0.1.3 → multimodalrouter-0.1.4/src/multiModalRouter.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multimodalrouter
-Version: 0.1.3
+Version: 0.1.4
 Summary: A graph-based routing library for dynamic routing.
 Author-email: Tobias Karusseit <karusseittobi@gmail.com>
 License: MIT License
@@ -51,6 +51,8 @@ Dynamic: license-file
 
 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
 
+> NEWS: v0.1.3 now on pypi ([installation guide](./docs/installation.md))
+
 > NOTE: This project is a work in progress and features might be added and or changed
 
 # In depth Documentation

{multimodalrouter-0.1.3 → multimodalrouter-0.1.4}/src/multimodalrouter/__init__.py

@@ -1,4 +1,4 @@
-from .graph import RouteGraph, Hub, EdgeMetadata, OptimizationMetric, Route, VerboseRoute
+from .graph import RouteGraph, Hub, EdgeMetadata, OptimizationMetric, Route, VerboseRoute, Filter
 from .utils import preprocessor
 
-__all__ = ["RouteGraph", "Hub", "EdgeMetadata", "OptimizationMetric", "Route", "VerboseRoute", "preprocessor"]
+__all__ = ["RouteGraph", "Hub", "EdgeMetadata", "OptimizationMetric", "Route", "VerboseRoute", "preprocessor", "Filter"]

{multimodalrouter-0.1.3 → multimodalrouter-0.1.4}/src/multimodalrouter/graph/__init__.py

@@ -1,2 +1,2 @@
 from .graph import RouteGraph # noqa: F401
-from .dataclasses import Hub, EdgeMetadata, OptimizationMetric, Route, VerboseRoute # noqa: F401
+from .dataclasses import Hub, EdgeMetadata, OptimizationMetric, Route, VerboseRoute, Filter # noqa: F401

{multimodalrouter-0.1.3 → multimodalrouter-0.1.4}/src/multimodalrouter/graph/dataclasses.py

@@ -5,6 +5,7 @@
 
 from dataclasses import dataclass
 from enum import Enum
+from abc import abstractmethod, ABC
 
 
 class OptimizationMetric(Enum):
@@ -49,7 +50,7 @@ class Hub:
         self.coords: list[float] = coords
         self.id = id
         self.hubType = hubType
-        self.outgoing = {}
+        self.outgoing: dict[str, dict[str, EdgeMetadata]] = {}
 
     def addOutgoing(self, mode: str, dest_id: str, metrics: EdgeMetadata):
         if mode not in self.outgoing:
@@ -104,3 +105,35 @@ class Route:
 class VerboseRoute(Route):
     """Uses base Route class but adds additional info to hold the edge metadata for every leg"""
     path: list[tuple[str, str, EdgeMetadata]]
+
+
+class Filter(ABC):
+
+    @abstractmethod
+    def filterEdge(self, edge: EdgeMetadata) -> bool:
+        """
+        Return True if you want to keep the edge else False
+
+        Args:
+            edge (EdgeMetadata): Edge to filter
+
+        Returns:
+            bool: True if you want to keep the edge
+        """
+        pass
+
+    @abstractmethod
+    def filterHub(self, hub: Hub) -> bool:
+        """
+        Return True if you want to keep the hub else False
+
+        Args:
+            hub (Hub): Hub to filter
+
+        Returns:
+            bool: True if you want to keep the hub
+        """
+        pass
+
+    def filter(self, start: Hub, end: Hub, edge: EdgeMetadata) -> bool:
+        return self.filterHub(start) and self.filterHub(end) and self.filterEdge(edge)

{multimodalrouter-0.1.3 → multimodalrouter-0.1.4}/src/multimodalrouter/graph/graph.py

@@ -9,8 +9,9 @@ import dill
 import heapq
 import os
 import pandas as pd
-from .dataclasses import Hub, EdgeMetadata, OptimizationMetric, Route
+from .dataclasses import Hub, EdgeMetadata, OptimizationMetric, Route, Filter
 from threading import Lock
+from collections import deque
 
 
 class RouteGraph:
@@ -371,10 +372,11 @@ class RouteGraph:
         self,
         start_id: str,
         end_id: str,
-        allowed_modes: list[str],
+        allowed_modes: list[str] = None,
         optimization_metric: OptimizationMetric | str = OptimizationMetric.DISTANCE,
         max_segments: int = 10,
-        verbose: bool = False
+        verbose: bool = False,
+        custom_filter: Filter = None,
     ) -> Route | None:
         """
         Find the optimal path between two hubs using Dijkstra
@@ -399,6 +401,9 @@ class RouteGraph:
         if end_hub is None:
             raise ValueError(f"End hub '{end_id}' not found in graph")
 
+        if allowed_modes is None:
+            allowed_modes = list(self.TransportModes.values())
+
         if start_id == end_id:
             # create a route with only the start hub
             # no verbose since no edges are needed
@@ -460,6 +465,15 @@ class RouteGraph:
                         if connection_metrics is None: # skip if the connection has no metrics
                             continue
 
+                        try:
+                            next_hub = self.getHubById(next_hub_id)
+                        except KeyError:
+                            raise ValueError(
+                                f"Hub with ID '{next_hub_id}' not found in graph! But it is connected to hub '{current_hub_id}' via mode '{mode}'." # noqa: E501
+                            )
+                        if custom_filter is not None and not custom_filter.filter(current_hub, next_hub, connection_metrics):
+                            continue
+
                         # get the selected metric alue for this connection
                         connection_value = connection_metrics.getMetric(optimization_metric)
                         new_metric_value = current_metric_value + connection_value
@@ -488,6 +502,65 @@ class RouteGraph:
 
         return None
 
+    def radial_search(
+        self,
+        hub_id: str,
+        radius: float,
+        optimization_metric: OptimizationMetric | str = OptimizationMetric.DISTANCE,
+        allowed_modes: list[str] = None,
+        custom_filter: Filter = None,
+    ) -> list[float, Hub]:
+        """
+        Find all hubs within a given radius of a given hub
+        (Note: distance is measured from the connecting paths not direct)
+
+        Args:
+            hub_id: ID of the center hub
+            radius: maximum distance from the center hub
+            optimization_metric: metric to optimize for (e.g. distance, time, cost)
+            allowed_modes: list of allowed transport modes (default: None => all modes)
+
+        Returns:
+            list of tuples containing the metric value and the corresponding hub object
+        """
+
+        center = self.getHubById(hub_id)
+        if center is None:
+            return [center]
+
+        if allowed_modes is None:
+            allowed_modes = list(self.TransportModes.values())
+
+        hubsToSearch = deque([center])
+        queued = set([hub_id])
+        reachableHubs: dict[str, tuple[float, Hub]] = {hub_id: (0.0, center)}
+
+        while hubsToSearch:
+            hub = hubsToSearch.popleft() # get the current hub to search
+            currentMetricVal, _ = reachableHubs[hub.id] # get the current metric value
+            for mode in allowed_modes:
+                outgoing = hub.outgoing.get(mode, {}) # find all outgoing connections
+                # dict like {dest_id: EdgeMetadata}
+                for id, edgemetadata in outgoing.items(): # iter over outgoing connections
+                    thisMetricVal = edgemetadata.getMetric(optimization_metric)
+                    if thisMetricVal is None:
+                        continue
+                    nextMetricVal = currentMetricVal + thisMetricVal
+                    if nextMetricVal > radius:
+                        continue
+                    knownMetric = reachableHubs.get(id, None)
+                    destHub = self.getHubById(id)
+                    if custom_filter is not None and not custom_filter.filter(hub, destHub, edgemetadata):
+                        continue
+                    # only save smaller metric values
+                    if knownMetric is None or knownMetric[0] > nextMetricVal:
+                        reachableHubs.update({id: (nextMetricVal, destHub)})
+                    if id not in queued:
+                        queued.add(id)
+                        hubsToSearch.append(destHub)
+
+        return [v for v in reachableHubs.values()]
+
     def compare_routes(
         self,
         start_id: str,