multimodalrouter 0.1.0__py3-none-any.whl

multimodalrouter/__init__.py

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

multimodalrouter/graph/__init__.py

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

multimodalrouter/graph/dataclasses.py

@@ -0,0 +1,106 @@
+# dataclasses.py
+# Copyright (c) 2025 Tobias Karusseit
+# Licensed under the MIT License. See LICENSE file in the project root for full license information.
+
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class OptimizationMetric(Enum):
+    DISTANCE = "distance"
+
+
+class EdgeMetadata:
+    __slots__ = ['transportMode', 'metrics']
+
+    def __init__(self, transportMode: str = None, **metrics):
+        self.transportMode = transportMode
+        self.metrics = metrics  # e.g., {"distance": 12.3, "time": 15} NOTE distance is required by the graph
+
+    def getMetric(self, metric: OptimizationMetric | str):
+        if isinstance(metric, str):
+            value = self.metrics.get(metric)
+            if value is None:
+                raise KeyError(f"Metric '{metric}' not found in EdgeMetadata")
+            return value
+
+        value = self.metrics.get(metric.value)
+        if value is None:
+            raise KeyError(f"Metric '{metric.value}' not found in EdgeMetadata")
+        return value
+
+    def copy(self):
+        return EdgeMetadata(transportMode=self.transportMode, **self.metrics)
+
+    @property
+    def allMetrics(self):
+        return self.metrics.copy()
+
+    def __str__(self):
+        return f"transportMode={self.transportMode}, metrics={self.metrics}"
+
+
+class Hub:
+    """Base hub class - using regular class instead of dataclass for __slots__ compatibility"""
+    __slots__ = ['coords', 'id', 'outgoing', 'hubType']
+
+    def __init__(self, coords: list[float], id: str, hubType: str):
+        self.coords: list[float] = coords
+        self.id = id
+        self.hubType = hubType
+        self.outgoing = {}
+
+    def addOutgoing(self, mode: str, dest_id: str, metrics: EdgeMetadata):
+        if mode not in self.outgoing:
+            self.outgoing[mode] = {}
+        self.outgoing[mode][dest_id] = metrics
+
+    def getMetrics(self, mode: str, dest_id: str) -> EdgeMetadata:
+        return self.outgoing.get(mode, {}).get(dest_id, None)
+
+    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 __hash__(self):
+        return hash((self.hubType, self.id))
+
+
+@dataclass
+class Route:
+    """Route class can use dataclass since it doesn't need __slots__"""
+    path: list[tuple[str, str]]
+    totalMetrics: EdgeMetadata
+    optimizedMetric: OptimizationMetric
+
+    @property
+    def optimizedValue(self):
+        return self.totalMetrics.getMetric(self.optimizedMetric)
+
+    @property
+    def flatPath(self, toStr=True):
+        """Flatten the path into a list of hub IDs"""
+        if not self.path:
+            return []
+        # get all source hubs plus the final destination
+        path = [edge for edge in self.path]
+        if not toStr:
+            return path
+        pathStr = ""
+        for i, edge in enumerate(path):
+            if i == 0:
+                pathStr += f"Start: {edge[0]}"
+                continue
+
+            if len(edge) > 2 and isinstance(edge[2], EdgeMetadata):
+                pathStr += f"\n\tEdge: ({str(edge[2])})\n-> {edge[0]}"
+            else:
+                pathStr += f"{edge[0]} -> {edge[1]}"
+        return pathStr
+
+
+@dataclass
+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]]

multimodalrouter/graph/graph.py

@@ -0,0 +1,513 @@
+# graph.py
+# Copyright (c) 2025 Tobias Karusseit
+# Licensed under the MIT License. See LICENSE file in the project root for full license information.
+
+
+from tqdm import tqdm
+import zlib
+import dill
+import heapq
+import os
+import pandas as pd
+from .dataclasses import Hub, EdgeMetadata, OptimizationMetric, Route
+from threading import Lock
+
+
+class RouteGraph:
+
+    def __init__(
+        self,
+        # sets the max distance to connect hubs with driving edges
+        maxDistance: float,
+        # dict like {hubtype -> "airport": "fly", "shippingport": "shipping"}
+        transportModes: dict[str, str],
+        # dict like {hubtype -> "airport": path -> "airports.csv", "shippingport": "shippingports.csv"}
+        dataPaths: dict[str, str] = {},
+        # if true model file will be compressed otherwise normal .dill file
+        compressed: bool = False,
+        # list of extra columns to add to the edge metadata (dynamically added to links when key is present in dataser)
+        extraMetricsKeys: list[str] = [],
+        # if true will connect hubs with driving edges
+        drivingEnabled: bool = True,
+        # a list of coordinate names for the source coords in the datasets (name to dataset matching is automatic)
+        sourceCoordKeys: list[str] = ["source_lat", "source_lng"],
+        # a list of coordinate names for the destination coords in the datasets (name to dataset matching is automatic)
+        destCoordKeys: list[str] = ["destination_lat", "destination_lng"],
+    ):
+        self.sourceCoordKeys = set(sourceCoordKeys)
+        self.destCoordKeys = set(destCoordKeys)
+
+        self.compressed = compressed
+        self.extraMetricsKeys = extraMetricsKeys
+        self.drivingEnabled = drivingEnabled
+
+        self.TransportModes = transportModes
+        # hubtype -> {hubid -> Hub}
+        self.Graph: dict[str, dict[str, Hub]] = {}
+
+        # save the paths to the data in the state dict
+        for key, value in dataPaths.items():
+            setattr(self, key + "DataPath", value)
+            self.Graph[key] = {}
+
+        self.maxDrivingDistance = maxDistance
+
+        self._lock = Lock()
+
+    def __getstate__(self):
+        state = self.__dict__.copy()
+
+        # remove attributes that break pickle
+        if "_lock" in state:
+            del state["_lock"]
+
+        return state
+
+    def __setstate__(self, state):
+        self.__dict__.update(state)
+        # set the lock for thread safety
+        from threading import Lock
+        self._lock = Lock()
+
+    # =========== public helpers ==========
+
+    def findClosestHub(self, allowedHubTypes: list[str], coords: list[float]) -> Hub | None:
+        """
+        Find the closest hub of a given type to a given location.
+
+        Args:
+            hubType: Type of hub to find
+            coords: list[float] = the coordinates of the location
+
+        Returns:
+            Hub instance if found, None otherwise
+        """
+        potentialHubs = []
+        if allowedHubTypes is not None:
+            for hubType in allowedHubTypes:
+                potentialHubs.extend(self.Graph.get(hubType, {}).values())
+
+        if allowedHubTypes is None:
+            potentialHubs = list(self._allHubs())
+
+        if not potentialHubs:
+            return None
+
+        tempHub = Hub(coords=coords, hubType="temp", id="temp")
+        distances = self._hubToHubDistances([tempHub], potentialHubs).flatten()  # shape (n,)
+        closest_hub = potentialHubs[distances.argmin()]
+        return closest_hub
+
+    def addHub(self, hub: Hub):
+        """
+        Add a hub to the graph. If the hub already exists, it will not be added a second time.
+
+        Args:
+            hub: Hub instance to add to the graph
+
+        Returns:
+            None
+        """
+        with self._lock:
+            hubType = hub.hubType
+            # if the hub type doesnt exist in the graph, create it first
+            if hubType not in self.Graph:
+                self.Graph[hubType] = {}
+            # exit if the hub already exists
+            if hub.id in self.Graph[hubType]:
+                return
+            # add the hub
+            self.Graph[hubType][hub.id] = hub
+
+    def getHub(self, hubType: str, id: str) -> Hub | None:
+        """
+        Get a hub from the graph by hub type and hub id.
+
+        Args:
+            hubType: Type of hub to get
+            id: ID of the hub to get
+
+        Returns:
+            Hub instance if found, None otherwise
+        """
+        return self.Graph.get(hubType, {}).get(id)
+
+    def getHubById(self, id: str) -> Hub | None:
+        """
+        Get a hub from the graph by its ID.
+
+        Args:
+            id: ID of the hub to get
+
+        Returns:
+            Hub instance if found, None otherwise
+        """
+        for hubType in self.Graph:
+            hub = self.Graph[hubType].get(id)
+            if hub:
+                return hub
+        return None
+
+    def save(
+        self,
+        filepath: str = os.path.join(os.getcwd(), "..", "..", "..", "data"),
+        compressed: bool = False
+    ):
+        """
+        Save the RouteGraph to a file.
+
+        Args:
+            filepath (str): Path to save the graph to.
+            saveMode (str, optional): Unused. Defaults to None.
+            compressed (bool, optional): Whether to compress the saved graph. Defaults to False.
+
+        Note: The graph is saved in the following format:
+            - Compressed: <filepath>.zlib
+            - Uncompressed: <filepath>.dill
+        """
+        with self._lock:
+
+            # ensure correct compression type is set for loading the graph
+            self.compressed = compressed
+            os.makedirs(filepath, exist_ok=True)
+            # save the graph
+            pickled = dill.dumps(self)
+            if compressed:
+                compressed = zlib.compress(pickled)
+                with open(os.path.join(filepath, "graph.zlib"), "wb") as f:
+                    f.write(compressed)
+            else:
+                with open(os.path.join(filepath, "graph.dill"), "wb") as f:
+                    f.write(pickled)
+
+    @staticmethod
+    def load(filepath: str, compressed: bool = False) -> "RouteGraph":
+        """
+        Load a RouteGraph from a file.
+
+        Args:
+            filepath (str): Path to load the graph from.
+            compressed (bool, optional): Whether the saved graph is compressed. Defaults to False.
+
+        Returns:
+            RouteGraph: The loaded graph.
+        """
+        with open(filepath, "rb") as f:
+            file_data = f.read()
+            if compressed:
+                decompressed = zlib.decompress(file_data)
+                graph = dill.loads(decompressed)
+            else:
+                graph = dill.loads(file_data)
+        return graph
+
+    # ============= private helpers =============
+
+    def _allHubs(self):
+        for hubType in self.Graph:
+            yield from self.Graph[hubType].values()
+
+    def _addLink(
+        self,
+        hub1: Hub,
+        hub2: Hub,
+        mode: str,
+        distance: float,
+        bidirectional: bool = False,
+        extraData: dict | None = None
+    ):
+        """
+        Add a connection between two hubs, dynamically storing extra metrics.
+        """
+        with self._lock:
+            if extraData is None:
+                extraData = {}
+            # combine required metrics with extra
+            metrics = {"distance": distance, **extraData}
+            edge = EdgeMetadata(transportMode=mode, **metrics)
+            hub1.addOutgoing(mode, hub2.id, edge)
+            if bidirectional:
+                hub2.addOutgoing(mode, hub1.id, edge.copy())
+
+    def _loadData(self, targetHubType: str):
+        dataPath = getattr(self, targetHubType + "DataPath")
+        if dataPath is None:
+            raise ValueError(f"Data path for {targetHubType} is not set")
+        fType = os.path.splitext(dataPath)[1]
+        if fType == ".csv":
+            data = pd.read_csv(dataPath)
+        elif fType == ".parquet":
+            data = pd.read_parquet(dataPath)
+        else:
+            raise ValueError(f"Unsupported file type {fType}")
+
+        if data.empty:
+            raise ValueError(f"{targetHubType} data is empty load the data first")
+
+        return data
+
+    def _generateHubs(self):
+        """
+        Generate Hub instances and link them with EdgeMetadata.
+        Extra columns in the data will be added to EdgeMetadata dynamically.
+        """
+        # no lock needed since underlying methods have locks
+        for hubType in self.Graph.keys():
+            data = self._loadData(hubType)
+            added = set()
+
+            thisSourceKeys = self.sourceCoordKeys & set(data.columns)
+            thisDestinationKeys = self.destCoordKeys & set(data.columns)
+
+            # get required and extra columns
+            required_cols = {
+                "source", "destination",
+                *thisSourceKeys,
+                *thisDestinationKeys,
+                "distance"
+            }
+
+            # collect extra data from the dataset columns that are not required but marked as extra
+            extra_metric_cols = []
+            for m in self.extraMetricsKeys:
+                if m not in required_cols:
+                    try:
+                        extra_metric_cols.append(m)
+                    except KeyError:
+                        continue
+
+            for row in tqdm(data.itertuples(index=False), desc=f"Generating {hubType} Hubs", unit="hub"):
+                # create hubs if they don't exist
+                if row.source not in added:
+                    hub = Hub(coords=[getattr(row, k) for k in thisSourceKeys], id=row.source, hubType=hubType)
+                    self.addHub(hub)
+                    added.add(row.source)
+
+                if row.destination not in added:
+                    hub = Hub(coords=[getattr(row, k) for k in thisDestinationKeys], id=row.destination, hubType=hubType)
+                    self.addHub(hub)
+                    added.add(row.destination)
+
+                # get extra metrics
+                extra_metrics = {col: getattr(row, col) for col in extra_metric_cols}
+
+                # link with the extra metrics
+                self._addLink(
+                    hub1=self.Graph[hubType][row.source],
+                    hub2=self.Graph[hubType][row.destination],
+                    mode=self.TransportModes[hubType],
+                    distance=row.distance, # distance metric is absolutely required for all links
+                    extraData=extra_metrics
+                )
+
+    def _hubToHubDistances(self, hub1: list[Hub], hub2: list[Hub]):
+        """
+        Compute full pairwise distance matrix between two lists of hubs using Haversine.
+
+        Args:
+            hub1: list of Hub
+            hub2: list of Hub
+
+        Returns:
+            numpy.ndarray of shape (len(hub1), len(hub2))
+        """
+        import torch
+        R = 6371.0
+        device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+        with torch.no_grad():
+            lat1 = torch.deg2rad(torch.tensor([h.coords[0] for h in hub1], device=device))
+            lng1 = torch.deg2rad(torch.tensor([h.coords[1] for h in hub1], device=device))
+            lat2 = torch.deg2rad(torch.tensor([h.coords[0] for h in hub2], device=device))
+            lng2 = torch.deg2rad(torch.tensor([h.coords[1] for h in hub2], device=device))
+
+            lat1 = lat1.unsqueeze(1)
+            lng1 = lng1.unsqueeze(1)
+            lat2 = lat2.unsqueeze(0)
+            lng2 = lng2.unsqueeze(0)
+
+            dlat = lat2 - lat1
+            dlng = lng2 - lng1
+
+            a = torch.sin(dlat / 2) ** 2 + torch.cos(lat1) * torch.cos(lat2) * torch.sin(dlng / 2) ** 2
+            c = 2 * torch.atan2(torch.sqrt(a), torch.sqrt(1 - a))
+            distances = R * c
+
+        return distances.cpu().numpy()
+
+    # ============= public key functions =============
+
+    def build(self):
+        self._generateHubs()
+        # exit here if not driving edges are allowed
+        if not self.drivingEnabled:
+            return
+
+        # build driving edges
+        hubTypes = list(self.Graph.keys())
+        for i, hubType1 in enumerate(hubTypes):
+            hubs1 = list(self.Graph[hubType1].values())
+            for _, hubType2 in enumerate(hubTypes[i:], start=i):
+                hubs2 = list(self.Graph[hubType2].values())
+                distances = self._hubToHubDistances(hubs1, hubs2)
+
+                for hi, hub1 in enumerate(hubs1):
+                    for hj, hub2 in enumerate(hubs2):
+                        if hub1.id == hub2.id:
+                            continue
+
+                        d = distances[hi, hj]
+                        if d <= self.maxDrivingDistance:
+                            self._addLink(
+                                hub1=hub1,
+                                hub2=hub2,
+                                mode="car",  # explicitly set driving
+                                distance=d,
+                                bidirectional=True,
+                                # no extra metrics for default drive nodes
+                            )
+
+    def find_shortest_path(
+        self,
+        start_id: str,
+        end_id: str,
+        allowed_modes: list[str],
+        optimization_metric: OptimizationMetric | str = OptimizationMetric.DISTANCE,
+        max_segments: int = 10,
+        verbose: bool = False
+    ) -> Route | None:
+        """
+        Find the optimal path between two hubs using Dijkstra
+
+        Args:
+            start_id: ID of the starting hub
+            end_id: ID of the destination hub
+            optimization_metric: Metric to optimize for (distance, time, cost, etc.) (must exist in EdgeMetadata)
+            allowed_modes: List of allowed transport modes (default: all modes)
+            max_segments: Maximum number of segments allowed in route
+
+        Returns:
+            Route object with the optimal path, or None if no path exists
+        """
+
+        # check if start and end hub exist
+        start_hub = self.getHubById(start_id)
+        end_hub = self.getHubById(end_id)
+
+        if start_hub is None:
+            raise ValueError(f"Start hub '{start_id}' not found in graph")
+        if end_hub is None:
+            raise ValueError(f"End hub '{end_id}' not found in graph")
+
+        if start_id == end_id:
+            # create a route with only the start hub
+            # no verbose since no edges are needed
+            return Route(
+                path=[(start_id, "")],
+                totalMetrics=EdgeMetadata(),
+                optimizedMetric=optimization_metric,
+            )
+
+        if verbose:
+            # priority queue: (metric_value, hub_id, path_with_modes, accumulated_metrics)
+            pq = [(0.0, start_id, [(start_id, "", EdgeMetadata())], EdgeMetadata())]
+        else:
+            # priority queue: (metric_value, hub_id, path_with_modes, accumulated_metrics)
+            pq = [(0.0, start_id, [(start_id, "")], EdgeMetadata())]
+
+        visited = {} # dict like {hub_id : metric_value}
+
+        while pq:
+            # get the current path data
+            # optim metric,         hub id,       path with modes, accumulated metrics (edgeMetadata object)
+            current_metric_value, current_hub_id, path_with_modes, accumulated_metrics = heapq.heappop(pq)
+
+            # skip this if a better path exists
+            if current_hub_id in visited and visited[current_hub_id] <= current_metric_value:
+                continue
+            # mark as visited
+            visited[current_hub_id] = current_metric_value
+
+            # check if this is the end hub
+            if current_hub_id == end_id:
+                if verbose:
+                    return Route(
+                        path=path_with_modes,
+                        totalMetrics=accumulated_metrics,
+                        optimizedMetric=optimization_metric,
+                    )
+
+                return Route(
+                    path=path_with_modes,
+                    totalMetrics=accumulated_metrics,
+                    optimizedMetric=optimization_metric,
+                )
+
+            # skip if too many segments
+            if len(path_with_modes) > max_segments:
+                continue
+
+            # get the current hub
+            current_hub = self.getHubById(current_hub_id)
+            if current_hub is None:
+                continue
+
+            # test all outgoing connections from the current hub
+            for mode in allowed_modes: # iter over the allowed transport modes
+                if mode in current_hub.outgoing: # check if the mode has outgoing connections
+                    # iter over all outgoing links with the selected transport type
+                    for next_hub_id, connection_metrics in current_hub.outgoing[mode].items():
+                        if connection_metrics is None: # skip if the connection has no 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
+
+                        # skip if a better hub to get here exists
+                        if next_hub_id in visited and visited[next_hub_id] <= new_metric_value:
+                            continue
+
+                        # create a new edge obj for the combined metrics  |  None bc modes my change between edges
+                        new_accumulated_metrics = EdgeMetadata(transportMode=None, **accumulated_metrics.metrics)
+                        # accumulate metrics
+                        for metric_name, metric_value in connection_metrics.metrics.items():
+                            if isinstance(metric_value, (int, float)):
+                                new_accumulated_metrics.metrics[metric_name] = new_accumulated_metrics.metrics.get(metric_name, 0) + metric_value # noqa: E501
+                            else:
+                                # ignore non-numeric metrics for accumulation (maybe combine strings here)
+                                new_accumulated_metrics.metrics[metric_name] = metric_value
+
+                        # combine to form a new path
+                        if verbose:
+                            new_path = path_with_modes + [(next_hub_id, mode, connection_metrics)]
+                        else:
+                            new_path = path_with_modes + [(next_hub_id, mode)]
+                        # push to the priority queue for future exploration
+                        heapq.heappush(pq, (new_metric_value, next_hub_id, new_path, new_accumulated_metrics))
+
+        return None
+
+    def compare_routes(
+        self,
+        start_id: str,
+        end_id: str,
+        allowed_modes: list[str],
+        metrics_to_compare: list[OptimizationMetric] = None
+    ) -> dict[OptimizationMetric, Route]:
+        """
+        Find optimal routes for different metrics and compare them
+
+        Returns:
+            Dictionary mapping each optimization metric to its optimal route
+        """
+        if metrics_to_compare is None:
+            metrics_to_compare = list(OptimizationMetric)
+
+        results = {}
+        for metric in metrics_to_compare:
+            route = self.find_shortest_path(start_id, end_id, optimization_metric=metric, allowed_modes=allowed_modes)
+            if route:
+                results[metric] = route
+
+        return results

multimodalrouter/router/build.py

@@ -0,0 +1,97 @@
+# build.py
+# Copyright (c) 2025 Tobias Karusseit
+# Licensed under the MIT License. See LICENSE file in the project root for full license information.
+
+
+from ..graph import RouteGraph
+import argparse
+import os
+
+
+def main():
+    print("Building graph...")
+    parser = argparse.ArgumentParser(
+        description="Collect key-value1-value2 triplets into two dicts"
+    )
+    parser.add_argument(
+        "data",
+        nargs="+",
+        help="Arguments in groups of 3: hubType transportMode dataPath"
+    )
+    parser.add_argument(
+        "--maxDist",
+        type=int,
+        default=50,
+        help="Maximum distance to connect hubs with driving edges"
+    )
+    parser.add_argument(
+        "--compressed",
+        action="store_true",
+        help="Whether to compress the saved graph (default: False)"
+    )
+
+    parser.add_argument(
+        "--extraMetrics",
+        nargs="+",
+        default=[],
+        help="Extra metrics to add to the edge metadata"
+    )
+
+    parser.add_argument(
+        "--drivingEnabled",
+        action="store_true",
+        default=True,
+        help="Whether to connect hubs with driving edges (default: True)"
+    )
+    path = os.path.dirname(os.path.abspath(__file__))
+    parser.add_argument(
+        "--Dir",
+        type=str,
+        default=os.path.join(path, "..", "..", "..", "data"),
+        help="Directory to save the graph in (default: .)"
+    )
+    parser.add_argument(
+        "--sourceKeys",
+        nargs="+",
+        default=["source_lat", "source_lng"],
+        help="Source keys to search the source coordinates for (default: ['source_lat', 'source_lng'])"
+    )
+    parser.add_argument(
+        "--destKeys",
+        nargs="+",
+        default=["destination_lat", "destination_lng"],
+        help="Destination keys to search the destination coordinates for (default: ['destination_lat', 'destination_lng'])"
+    )
+
+    args = parser.parse_args()
+
+    if len(args.data) % 3 != 0:
+        parser.error("Arguments must be in groups of 3: hubType transportMode dataPath")
+
+    transportModes = {}
+    dataPaths = {}
+
+    for i in range(0, len(args.data), 3):
+        key, val1, val2 = args.data[i], args.data[i + 1], args.data[i + 2]
+        transportModes[key] = val1
+        dataPaths[key] = val2
+
+    graph = RouteGraph(
+        maxDistance=args.maxDist,
+        transportModes=transportModes,
+        dataPaths=dataPaths,
+        compressed=args.compressed,
+        extraMetricsKeys=args.extraMetrics,
+        drivingEnabled=args.drivingEnabled,
+        sourceCoordKeys=args.sourceKeys,
+        destCoordKeys=args.destKeys
+    )
+
+    graph.build()
+    graph.save(filepath=args.Dir, compressed=args.compressed)
+
+    print("Graph built and saved.")
+
+
+if __name__ == "__main__":
+    main()

multimodalrouter/router/route.py

@@ -0,0 +1,71 @@
+# router.py
+# Copyright (c) 2025 Tobias Karusseit
+# Licensed under the MIT License. See LICENSE file in the project root for full license information.
+
+
+from ..graph import RouteGraph
+import argparse
+import os
+
+
+def main():
+    graph = RouteGraph.load(
+        os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "..", "data", "graph.dill"),
+        compressed=False
+    )
+
+    parser = argparse.ArgumentParser(
+        description="parse the arguments"
+    )
+    parser.add_argument(
+        "--start",
+        nargs="+",
+        type=float,
+        required=True,
+        help="Start coordinates"
+    )
+    parser.add_argument(
+        "--end",
+        nargs="+",
+        type=float,
+        required=True,
+        help="End coordinates"
+    )
+    parser.add_argument(
+        "--allowedModes",
+        nargs="+",
+        type=str,
+        default=["car"],
+        help="Allowed transport modes"
+    )
+    parser.add_argument(
+        "--maxSegments",
+        type=int,
+        default=10,
+        help="Maximum number of segments in the route"
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Verbose output for the paths"
+    )
+    args = parser.parse_args()
+
+    start_hub = graph.findClosestHub(["airport"], args.start)
+    end_hub = graph.findClosestHub(["airport"], args.end)
+
+    if start_hub is None or end_hub is None:
+        print("One of the airports does not exist in the graph")
+        return
+
+    route = graph.find_shortest_path(start_id=start_hub.id,
+                                     end_id=end_hub.id,
+                                     allowed_modes=args.allowedModes,
+                                     max_segments=args.maxSegments,
+                                     verbose=args.verbose)
+
+    print(route.flatPath if route else "No route found")
+
+
+if __name__ == "__main__":
+    main()

multimodalrouter/utils/__init__.py

@@ -0,0 +1 @@
+from .preprocessor import preprocessor # noqa: F401

multimodalrouter/utils/preprocessor.py

@@ -0,0 +1,177 @@
+# preprocessor.py
+# Copyright (c) 2025 Tobias Karusseit
+# Licensed under the MIT License. See LICENSE file in the project root for full license information.
+
+
+import pandas as pd
+import os
+
+# all datasets need:
+# 1. source
+# 2. destination
+# 3. distance
+# 4. source lat
+# 5. source lng
+# 6. destination lat
+# 7. destination lng
+
+
+class preprocessor:
+
+    @staticmethod
+    def _save(
+        df: pd.DataFrame,
+        targetType: str = "parquet"
+    ) -> None:
+        """
+        Save the DataFrame to a file in the data directory.
+
+        Parameters:
+            df (pd.DataFrame): The DataFrame to be saved.
+            targetType (str): The type of file to be saved. Defaults to "parquet".
+        """
+        from pathlib import Path
+
+        # create data directory if it doesn't exist (should be on te same level as this parent folder)
+        data_dir = Path(__file__).parent.parent / "data"
+        data_dir.mkdir(parents=True, exist_ok=True)
+        file_path = data_dir / f"fullDataset.{targetType}"
+
+        if targetType == "csv":
+            # Save the DataFrame to a csv file
+            df.to_csv(file_path, index=False)
+        else:
+            # Save the DataFrame to a parquet file
+            df.to_parquet(file_path, engine="pyarrow")
+
+    @staticmethod
+    def preprocess(
+        path: str,
+        sourceKey: str = "source",
+        sourceNameKey: str = "source_name",
+        destinationKey: str = "destination",
+        destinationNameKey: str = "destination_name",
+        distanceKey: str = "distance",
+        sourceLatKey: str = "source_lat",
+        sourceLngKey: str = "source_lng",
+        destinationLatKey: str = "destination_lat",
+        destinationLngKey: str = "destination_lng",
+        targetType: str = "parquet"
+    ) -> pd.DataFrame:
+        """
+        Preprocess a dataset by renaming columns to the desired format,
+        calculating distances and adding the result to the dataframe.
+
+        Parameters:
+        path (str): path to the dataset
+        sourceKey (str): key for the source column (default: "source")
+        destinationKey (str): key for the destination column (default: "destination")
+        distanceKey (str): key for the distance column (default: "distance")
+        sourceLatKey (str): key for the source latitude column (default: "source_lat")
+        sourceLngKey (str): key for the source longitude column (default: "source_lng")
+        destinationLatKey (str): key for the destination latitude column (default: "destination_lat")
+        destinationLngKey (str): key for the destination longitude column (default: "destination_lng")
+
+        Returns:
+        pd.DataFrame: the preprocessed dataframe
+        """
+
+        # check if file exists and read it into a df
+        _, fType = os.path.splitext(path)
+        if fType == ".csv":
+            df = pd.read_csv(path)
+        elif fType == ".parquet":
+            df = pd.read_parquet(path)
+
+        # get all column names
+        cols = list(df.columns)
+
+        # check if all required columns are present
+        if any([
+            sourceKey not in cols,
+            sourceNameKey not in cols,
+            destinationKey not in cols,
+            destinationNameKey not in cols,
+            sourceLatKey not in cols,
+            sourceLngKey not in cols,
+            destinationLatKey not in cols,
+            destinationLngKey not in cols
+        ]):
+            raise Exception("Invalid dataset")
+
+        # rename columns to the desired format
+        df.rename(columns={
+            sourceKey: "source",
+            sourceNameKey: "source_name",
+            destinationKey: "destination",
+            destinationNameKey: "destination_name",
+            sourceLatKey: "source_lat",
+            sourceLngKey: "source_lng",
+            destinationLatKey: "destination_lat",
+            destinationLngKey: "destination_lng",
+            **({distanceKey: "distance"} if distanceKey in cols else {})
+        }, inplace=True)
+
+        # distance is already present return here
+        if distanceKey in cols:
+            preprocessor._save(df, targetType=targetType)
+            return df[[
+                "source",
+                "source_name",
+                "destination",
+                "destination_name",
+                "distance",
+                "source_lat",
+                "source_lng",
+                "destination_lat",
+                "destination_lng"
+            ]]
+
+        # calculate distance
+        df["distance"] = preprocessor.haversine(df)
+
+        # save df
+        preprocessor._save(df, targetType=targetType)
+        # return processed df
+        return df[[
+            "source",
+            "source_name"
+            "destination",
+            "destination_name",
+            "distance",
+            "source_lat",
+            "source_lng",
+            "destination_lat",
+            "destination_lng"
+        ]]
+
+    @staticmethod
+    def haversine(df: pd.DataFrame) -> float:
+        # use torch for vector calculation
+        import torch
+        # set device
+        device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        # compute vectorized haversine
+        with torch.no_grad():
+            # convert to radians
+            lat1 = torch.deg2rad(torch.tensor(df["source_lat"].values, device=device))
+            lng1 = torch.deg2rad(torch.tensor(df["source_lng"].values, device=device))
+            lat2 = torch.deg2rad(torch.tensor(df["destination_lat"].values, device=device))
+            lng2 = torch.deg2rad(torch.tensor(df["destination_lng"].values, device=device))
+
+            # compute delta lat and delta lng
+            dlat = lat2 - lat1
+            dlng = lng2 - lng1
+            # compute haversine
+            a = torch.sin(dlat / 2)**2 + torch.cos(lat1) * torch.cos(lat2) * torch.sin(dlng / 2)**2
+            c = 2 * torch.atan2(torch.sqrt(a), torch.sqrt(1 - a))
+
+            distances = 6371 * c
+
+            return distances.cpu().numpy()
+
+    @staticmethod
+    def combine(df1: pd.DataFrame, df2: pd.DataFrame) -> pd.DataFrame:
+        # Combine the two DataFrames
+        combined_df = pd.concat([df1, df2], axis=0)
+        return combined_df

multimodalrouter-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: multimodalrouter
+Version: 0.1.0
+Summary: A graph-based routing library for dynamic routing.
+Author-email: Tobias Karusseit <karusseittobi@gmail.com>
+License: 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.
+        
+        
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: dill>=0.4.0
+Requires-Dist: filelock>=3.19.1
+Requires-Dist: fsspec>=2025.9.0
+Requires-Dist: Jinja2>=3.1.6
+Requires-Dist: MarkupSafe>=3.0.2
+Requires-Dist: mpmath>=1.3.0
+Requires-Dist: networkx>=3.5
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: pandas>=2.3.2
+Requires-Dist: parquet>=1.3.1
+Requires-Dist: ply>=3.11
+Requires-Dist: pyarrow>=21.0.0
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: pytz>=2025.2
+Requires-Dist: setuptools>=80.9.0
+Requires-Dist: six>=1.17.0
+Requires-Dist: sympy>=1.14.0
+Requires-Dist: thriftpy2>=0.5.3
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: typing_extensions>=4.15.0
+Requires-Dist: tzdata>=2025.2
+Provides-Extra: torch
+Requires-Dist: torch>=2.8.0; extra == "torch"
+Dynamic: license-file
+
+# 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](./docs/installation.md)
+
+[graph module documentation](./docs/graph.md)
+
+[code examples](./docs/examples/demo.py)
+
+[command line interface documentation](./docs/cli.md)
+
+[utilities documentation](./docs/utils.md)
+
+
+# Features
+
+## Building Freedom / Unlimited Usecases
+
+The graph can be build from any data aslong as the required fields are present ([example](./docs/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](./docs/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](./docs/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](./docs/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](./docs/examples/mazePathfinder/main.py)
+
+![example from the maze solver](./docs/solvedMaze1.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](./docs/graph.md#args) or do [this](./docs/graph.md#swap-distance-method)|
+| NO | degrees | None | distances must be calculated when [preprocessing](./src/multimodalrouter/utils/preprocessor.py) |
+| NO | not degrees | **ALL** | **U cant build the graph with neither distances or supported coordinates!** [**solution**](./docs/graph.md#swap-distance-method)
+
+[**example dataframe with the required fields**](./docs/examples/demoData.csv)
+
+### License
+
+[see here](./LICENSE.md)
+
+

multimodalrouter-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+multimodalrouter/__init__.py,sha256=3O9ft058b5x09ORYD8Luw1qyEYoAx4kFPMjBs2HkfBM,238
+multimodalrouter/graph/__init__.py,sha256=FSIR6ZN-IM0r-NRcM81AiPn2FVe9fA8rkc9r2746Lr4,142
+multimodalrouter/graph/dataclasses.py,sha256=Bmcg3NFfFyPJS2sJO-IO0TnNCJ_pCG_n9lfJKVvFjxI,3535
+multimodalrouter/graph/graph.py,sha256=UPFcFIxhlJ1gfpHG8mPWAGiRjxVgEy_VTv16AneSjYM,19944
+multimodalrouter/router/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+multimodalrouter/router/build.py,sha256=jrGcFyVS7-Qg6CXAVVwiXM_krLBHBoRH85Slknmutns,2843
+multimodalrouter/router/route.py,sha256=5RZGFgrTYm930RJX6i26d8f8_k7CGnp5lKZJBM1gcKk,1956
+multimodalrouter/utils/__init__.py,sha256=jsZ7cBB-9otxzMiN9FVviGuknxnOPmaG2RBbZuiezeg,53
+multimodalrouter/utils/preprocessor.py,sha256=45ya0cg0PGCV3YMk680_HZUve1QGJ7JHPSHoRvYdleY,6333
+multimodalrouter-0.1.0.dist-info/licenses/LICENSE.md,sha256=CRtvaQsLnzHvSIzusV5sHHw-e8w8gytXq8R7AP1GBmE,1092
+multimodalrouter-0.1.0.dist-info/METADATA,sha256=3RjttBFNt2KNlw5XUijSc-wGVKid5PbL8-BpQxplX4k,5766
+multimodalrouter-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+multimodalrouter-0.1.0.dist-info/entry_points.txt,sha256=vp177Z2KMWPGJkS_dVpX05LVtBYssdlyYhTCG0kYmjo,138
+multimodalrouter-0.1.0.dist-info/top_level.txt,sha256=4RYMG9hyl8mDNJ_gTrlh8QdYjZNXLDBzFVK1PcTpAYg,17
+multimodalrouter-0.1.0.dist-info/RECORD,,

multimodalrouter-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

multimodalrouter-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+multiModalRouter-build = multimodalrouter.router.build:main
+multiModalRouter-route = multimodalrouter.router.route:main

multimodalrouter-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,10 @@
+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.
+

multimodalrouter-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+multimodalrouter