allocator 1.0.0__py3-none-any.whl

allocator/cli/route_cmd.py

@@ -0,0 +1,164 @@
+"""
+Routing CLI commands.
+"""
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+@click.command()
+@click.argument("input_file", type=click.Path(exists=True))
+@click.option(
+    "--method",
+    "-m",
+    default="christofides",
+    type=click.Choice(["christofides", "ortools", "osrm", "google"]),
+    help="TSP solving method",
+)
+@click.option(
+    "--distance",
+    "-d",
+    default="euclidean",
+    type=click.Choice(["euclidean", "haversine", "osrm", "google"]),
+    help="Distance metric to use",
+)
+@click.option("--output", "-o", type=click.Path(), help="Output file path")
+@click.option(
+    "--format",
+    "output_format",
+    default="csv",
+    type=click.Choice(["csv", "json"]),
+    help="Output format",
+)
+@click.option("--api-key", help="API key for Google services")
+@click.option("--osrm-base-url", help="Custom OSRM server URL")
+@click.pass_context
+def tsp(ctx, input_file, method, distance, output, output_format, api_key, osrm_base_url):
+    """Solve Traveling Salesman Problem (TSP) for geographic points."""
+    from ..api import shortest_path
+    from ..io.data_handler import DataHandler
+
+    try:
+        # Prepare kwargs
+        kwargs = {}
+        if api_key:
+            kwargs["api_key"] = api_key
+        if osrm_base_url:
+            kwargs["osrm_base_url"] = osrm_base_url
+
+        # Run TSP solver
+        result = shortest_path(input_file, method=method, distance=distance, **kwargs)
+
+        if ctx.obj.get("verbose"):
+            console.print(f"[green]TSP solved using {method}[/green]")
+            console.print(f"Total distance: {result.total_distance:.2f}")
+            console.print(f"Route length: {len(result.route)} points")
+
+        # Save results
+        if output:
+            DataHandler.save_results(result, output, format=output_format)
+            console.print(f"[green]Results saved to {output}[/green]")
+        else:
+            console.print(f"\nOptimal route: {result.route}")
+            console.print(f"Total distance: {result.total_distance:.2f}")
+
+    except NotImplementedError:
+        console.print(f"[yellow]{method} TSP solver will be implemented in Phase 5[/yellow]")
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise click.Abort() from e
+
+
+@click.command()
+@click.argument("input_file", type=click.Path(exists=True))
+@click.option(
+    "--distance",
+    "-d",
+    default="euclidean",
+    type=click.Choice(["euclidean", "haversine"]),
+    help="Distance metric to use",
+)
+@click.option("--output", "-o", type=click.Path(), help="Output file path")
+@click.option(
+    "--format",
+    "output_format",
+    default="csv",
+    type=click.Choice(["csv", "json"]),
+    help="Output format",
+)
+@click.pass_context
+def christofides(ctx, input_file, distance, output, output_format):
+    """Solve TSP using Christofides algorithm (approximate)."""
+    from ..api import tsp_christofides
+    from ..io.data_handler import DataHandler
+
+    try:
+        result = tsp_christofides(input_file, distance=distance)
+
+        if ctx.obj.get("verbose"):
+            console.print("[green]TSP solved using Christofides algorithm[/green]")
+            console.print(f"Total distance: {result.total_distance:.2f}")
+
+        if output:
+            DataHandler.save_results(result, output, format=output_format)
+            console.print(f"[green]Results saved to {output}[/green]")
+        else:
+            console.print(f"\nOptimal route: {result.route}")
+            console.print(f"Total distance: {result.total_distance:.2f}")
+
+    except NotImplementedError:
+        console.print("[yellow]Christofides TSP will be implemented in Phase 5[/yellow]")
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise click.Abort() from e
+
+
+@click.command()
+@click.argument("input_file", type=click.Path(exists=True))
+@click.option(
+    "--distance",
+    "-d",
+    default="euclidean",
+    type=click.Choice(["euclidean", "haversine", "osrm"]),
+    help="Distance metric to use",
+)
+@click.option("--output", "-o", type=click.Path(), help="Output file path")
+@click.option(
+    "--format",
+    "output_format",
+    default="csv",
+    type=click.Choice(["csv", "json"]),
+    help="Output format",
+)
+@click.option("--osrm-base-url", help="Custom OSRM server URL")
+@click.pass_context
+def ortools(ctx, input_file, distance, output, output_format, osrm_base_url):
+    """Solve TSP using Google OR-Tools (exact for small problems)."""
+    from ..api import tsp_ortools
+    from ..io.data_handler import DataHandler
+
+    try:
+        kwargs = {}
+        if osrm_base_url:
+            kwargs["osrm_base_url"] = osrm_base_url
+
+        result = tsp_ortools(input_file, distance=distance, **kwargs)
+
+        if ctx.obj.get("verbose"):
+            console.print("[green]TSP solved using OR-Tools[/green]")
+            console.print(f"Total distance: {result.total_distance:.2f}")
+
+        if output:
+            DataHandler.save_results(result, output, format=output_format)
+            console.print(f"[green]Results saved to {output}[/green]")
+        else:
+            console.print(f"\nOptimal route: {result.route}")
+            console.print(f"Total distance: {result.total_distance:.2f}")
+
+    except NotImplementedError:
+        console.print("[yellow]OR-Tools TSP will be implemented in Phase 5[/yellow]")
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise click.Abort() from e

allocator/core/__init__.py

@@ -0,0 +1 @@
+"""Core algorithms for clustering and optimization."""

allocator/core/algorithms.py

@@ -0,0 +1,200 @@
+"""
+Pure algorithm implementations without CLI, plotting, or file I/O.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+import numpy as np
+import pandas as pd
+
+from ..distances import get_distance_matrix
+
+
+def initialize_centroids(points: np.ndarray, k: int, random_state: int | None = None) -> np.ndarray:
+    """
+    Initialize k centroids by randomly selecting from points.
+
+    Args:
+        points: Input points array with shape [n, 2]
+        k: Number of centroids
+        random_state: Random seed for reproducibility
+
+    Returns:
+        Array of k initial centroids
+    """
+    if random_state is not None:
+        rng = np.random.RandomState(random_state)
+        rng_state = rng.get_state()
+        np.random.set_state(rng_state)
+
+    centroids = points.copy()
+    np.random.shuffle(centroids)
+    return centroids[:k]
+
+
+def move_centroids(points: np.ndarray, closest: np.ndarray, centroids: np.ndarray) -> np.ndarray:
+    """
+    Update centroids to the mean of their assigned points.
+
+    Args:
+        points: All data points
+        closest: Array indicating which centroid each point belongs to
+        centroids: Current centroids
+
+    Returns:
+        Updated centroids
+    """
+    new_centroids = [points[closest == k].mean(axis=0) for k in range(centroids.shape[0])]
+
+    # Handle empty clusters by keeping old centroid
+    for i, c in enumerate(new_centroids):
+        if np.isnan(c).any():
+            new_centroids[i] = centroids[i]
+
+    return np.array(new_centroids)
+
+
+def kmeans_cluster(
+    data: pd.DataFrame | np.ndarray,
+    n_clusters: int,
+    distance_method: str = "euclidean",
+    max_iter: int = 300,
+    random_state: int | None = None,
+    **distance_kwargs,
+) -> dict:
+    """
+    Pure K-means clustering implementation.
+
+    Args:
+        data: Input data as DataFrame with longitude/latitude or numpy array [n, 2]
+        n_clusters: Number of clusters
+        distance_method: Distance calculation method
+        max_iter: Maximum iterations
+        random_state: Random seed
+        **distance_kwargs: Additional arguments for distance calculation
+
+    Returns:
+        Dictionary with 'labels', 'centroids', 'iterations', 'converged'
+    """
+    # Convert DataFrame to numpy array if needed
+    if isinstance(data, pd.DataFrame):
+        if "longitude" in data.columns and "latitude" in data.columns:
+            X = data[["longitude", "latitude"]].values
+        else:
+            raise ValueError("DataFrame must contain 'longitude' and 'latitude' columns")
+    else:
+        X = np.asarray(data)
+
+    # Initialize centroids
+    centroids = initialize_centroids(X, n_clusters, random_state)
+    old_centroids = centroids.copy()
+
+    for i in range(max_iter):
+        # Calculate distances and assign points to closest centroids
+        distances = get_distance_matrix(X, centroids, method=distance_method, **distance_kwargs)
+        labels = np.argmin(distances, axis=1)
+
+        # Update centroids
+        centroids = move_centroids(X, labels, centroids)
+
+        # Check for convergence
+        if np.allclose(old_centroids, centroids, rtol=1e-4):
+            return {
+                "labels": labels,
+                "centroids": centroids,
+                "iterations": i + 1,
+                "converged": True,
+            }
+
+        old_centroids = centroids.copy()
+
+    return {"labels": labels, "centroids": centroids, "iterations": max_iter, "converged": False}
+
+
+def sort_by_distance_assignment(
+    data: pd.DataFrame | np.ndarray,
+    centroids: np.ndarray,
+    distance_method: str = "euclidean",
+    **distance_kwargs,
+) -> np.ndarray:
+    """
+    Assign points to closest centroids (used by sort_by_distance).
+
+    Args:
+        data: Input data as DataFrame or numpy array
+        centroids: Centroid locations
+        distance_method: Distance calculation method
+        **distance_kwargs: Additional arguments for distance calculation
+
+    Returns:
+        Array of cluster assignments
+    """
+    # Convert DataFrame to numpy array if needed
+    if isinstance(data, pd.DataFrame):
+        if "longitude" in data.columns and "latitude" in data.columns:
+            X = data[["longitude", "latitude"]].values
+        else:
+            raise ValueError("DataFrame must contain 'longitude' and 'latitude' columns")
+    else:
+        X = np.asarray(data)
+
+    # Calculate distances and assign to closest
+    distances = get_distance_matrix(X, centroids, method=distance_method, **distance_kwargs)
+    labels = np.argmin(distances, axis=1)
+
+    return labels
+
+
+def calculate_cluster_statistics(
+    data: pd.DataFrame, labels: np.ndarray, distance_method: str = "euclidean", **distance_kwargs
+) -> list[dict]:
+    """
+    Calculate statistics for each cluster (used by comparison functions).
+
+    Args:
+        data: Input data with coordinates
+        labels: Cluster assignments
+        distance_method: Distance calculation method
+        **distance_kwargs: Additional arguments for distance calculation
+
+    Returns:
+        List of dictionaries with cluster statistics
+    """
+
+    results = []
+    X = data[["longitude", "latitude"]].values
+
+    for cluster_id in sorted(np.unique(labels)):
+        cluster_points = X[labels == cluster_id]
+        n_points = len(cluster_points)
+
+        if n_points <= 1:
+            # Skip clusters with 0 or 1 points
+            continue
+
+        # Calculate distance matrix for this cluster
+        distances = get_distance_matrix(
+            cluster_points, cluster_points, method=distance_method, **distance_kwargs
+        )
+
+        if distances is None:
+            continue
+
+        # Create graph and calculate MST
+        G = nx.from_numpy_matrix(distances)
+        T = nx.minimum_spanning_tree(G)
+
+        graph_weight = int(G.size(weight="weight") / 1000)
+        mst_weight = int(T.size(weight="weight") / 1000)
+
+        results.append(
+            {
+                "label": cluster_id,
+                "n": n_points,
+                "graph_weight": graph_weight,
+                "mst_weight": mst_weight,
+            }
+        )
+
+    return results

allocator/core/routing.py

@@ -0,0 +1,242 @@
+"""
+Pure routing/TSP algorithm implementations.
+"""
+
+from __future__ import annotations
+
+import googlemaps
+import networkx as nx
+import numpy as np
+import requests
+from ortools.constraint_solver import pywrapcp, routing_enums_pb2
+
+from ..distances import get_distance_matrix
+
+
+def solve_tsp_ortools(
+    points: np.ndarray, distance_method: str = "euclidean", **distance_kwargs
+) -> tuple[float, list[int]]:
+    """
+    Solve TSP using Google OR-Tools.
+
+    Args:
+        points: Array of [lon, lat] coordinates
+        distance_method: Distance calculation method
+        **distance_kwargs: Additional args for distance calculation
+
+    Returns:
+        (total_distance, route) tuple
+    """
+    # Check for empty data
+    if len(points) == 0:
+        raise ValueError("Cannot solve TSP with empty data")
+
+    # Check for single point
+    if len(points) == 1:
+        return 0.0, [0, 0]  # Visit same point twice
+
+    # Get distance matrix
+    distances = get_distance_matrix(points, points, method=distance_method, **distance_kwargs)
+
+    if distances is None:
+        raise ValueError("Could not calculate distance matrix")
+
+    # Create routing model with index manager
+    tsp_size = len(points)
+    num_vehicles = 1
+    depot = 0
+
+    # Create the routing index manager
+    manager = pywrapcp.RoutingIndexManager(tsp_size, num_vehicles, depot)
+
+    # Create routing model
+    routing = pywrapcp.RoutingModel(manager)
+
+    # Set up distance callback
+    def distance_callback(from_index, to_index):
+        # Convert from routing variable Index to distance matrix NodeIndex
+        from_node = manager.IndexToNode(from_index)
+        to_node = manager.IndexToNode(to_index)
+        return int(distances[from_node, to_node])
+
+    transit_callback_index = routing.RegisterTransitCallback(distance_callback)
+    routing.SetArcCostEvaluatorOfAllVehicles(transit_callback_index)
+
+    # Set search parameters
+    search_params = pywrapcp.DefaultRoutingSearchParameters()
+    search_params.first_solution_strategy = (
+        routing_enums_pb2.FirstSolutionStrategy.PATH_CHEAPEST_ARC
+    )
+
+    # Solve
+    assignment = routing.SolveWithParameters(search_params)
+
+    if not assignment:
+        return float("inf"), []
+
+    # Extract tour
+    tour = []
+    index = routing.Start(0)
+    while not routing.IsEnd(index):
+        tour.append(manager.IndexToNode(index))
+        index = assignment.Value(routing.NextVar(index))
+    tour.append(manager.IndexToNode(index))  # Return to start (depot)
+
+    total_distance = assignment.ObjectiveValue()
+
+    return float(total_distance), tour
+
+
+def solve_tsp_christofides(
+    points: np.ndarray, distance_method: str = "euclidean", **distance_kwargs
+) -> tuple[float, list[int]]:
+    """
+    Solve TSP using Christofides algorithm (approximate).
+
+    Args:
+        points: Array of [lon, lat] coordinates
+        distance_method: Distance calculation method
+        **distance_kwargs: Additional args for distance calculation
+
+    Returns:
+        (total_distance, route) tuple
+    """
+    try:
+        from Christofides import christofides
+    except ImportError as e:
+        raise ImportError(
+            "Christofides algorithm requires the 'Christofides' package. "
+            "Install it with: pip install Christofides"
+        ) from e
+
+    # Get distance matrix
+    distances = get_distance_matrix(points, points, method=distance_method, **distance_kwargs)
+
+    if distances is None:
+        raise ValueError("Could not calculate distance matrix")
+
+    # Create complete graph from distance matrix
+    G = nx.Graph()
+    n = len(points)
+
+    for i in range(n):
+        for j in range(i + 1, n):
+            G.add_edge(i, j, weight=distances[i, j])
+
+    # Solve using Christofides algorithm
+    tour = christofides(G, 0)  # Start from node 0
+
+    # Calculate total distance
+    total_distance = 0.0
+    for i in range(len(tour) - 1):
+        total_distance += distances[tour[i], tour[i + 1]]
+
+    return total_distance, tour
+
+
+def solve_tsp_osrm(
+    points: np.ndarray, osrm_base_url: str | None = None, **kwargs
+) -> tuple[float, list[int]]:
+    """
+    Solve TSP using OSRM trip service.
+
+    Args:
+        points: Array of [lon, lat] coordinates
+        osrm_base_url: Custom OSRM server URL
+        **kwargs: Additional arguments
+
+    Returns:
+        (total_distance, route) tuple
+    """
+
+    if osrm_base_url is None:
+        osrm_base_url = "http://router.project-osrm.org"
+
+    # Format coordinates for OSRM (lon,lat format)
+    coords = ";".join([f"{point[0]},{point[1]}" for point in points])
+
+    # Build OSRM trip URL
+    url = f"{osrm_base_url}/trip/v1/driving/{coords}"
+    params = {
+        "source": "first",
+        "destination": "last",
+        "roundtrip": "true",
+        "steps": "false",
+        "geometries": "polyline",
+    }
+
+    try:
+        response = requests.get(url, params=params, timeout=30)
+        response.raise_for_status()
+        data = response.json()
+
+        if data["code"] != "Ok":
+            raise ValueError(f"OSRM error: {data.get('message', 'Unknown error')}")
+
+        trip = data["trips"][0]
+        total_distance = trip["distance"]  # meters
+
+        # Extract waypoint order
+        waypoints = trip["legs"]
+        route = [0]  # Start with first point
+
+        # OSRM returns the optimal order
+        for _leg in waypoints:
+            # This is simplified - real implementation would need to parse the leg structure
+            pass
+
+        # For now, return a simple route (this would need proper OSRM response parsing)
+        route = [*list(range(len(points))), 0]  # Simple circular tour
+
+        return total_distance, route
+
+    except requests.RequestException as e:
+        raise ValueError(f"OSRM request failed: {e}") from e
+
+
+def solve_tsp_google(points: np.ndarray, api_key: str, **kwargs) -> tuple[float, list[int]]:
+    """
+    Solve TSP using Google Maps Directions API.
+
+    Args:
+        points: Array of [lon, lat] coordinates
+        api_key: Google Maps API key
+        **kwargs: Additional arguments
+
+    Returns:
+        (total_distance, route) tuple
+    """
+    gmaps = googlemaps.Client(key=api_key)
+
+    # Convert points to lat,lng format for Google
+    locations = [(point[1], point[0]) for point in points]  # Google uses lat,lng
+
+    # This is a simplified implementation
+    # A full implementation would use the Google Directions API with waypoints
+    # and potentially solve the TSP optimization externally
+
+    # For now, return a basic circular tour
+    n = len(points)
+    route = [*list(range(n)), 0]
+
+    # Calculate approximate distance using Google Distance Matrix
+    try:
+        matrix = gmaps.distance_matrix(
+            origins=locations, destinations=locations, mode="driving", units="metric"
+        )
+
+        total_distance = 0
+        for i in range(len(route) - 1):
+            from_idx = route[i]
+            to_idx = route[i + 1]
+            distance_info = matrix["rows"][from_idx]["elements"][to_idx]
+
+            if distance_info["status"] == "OK":
+                total_distance += distance_info["distance"]["value"]  # meters
+            else:
+                raise ValueError(f"Google Maps error: {distance_info['status']}")
+
+        return float(total_distance), route
+
+    except Exception as e:
+        raise ValueError(f"Google Maps API error: {e}") from e

allocator/distances/__init__.py

@@ -0,0 +1,17 @@
+"""Distance matrix calculations."""
+
+from .euclidean import euclidean_distance_matrix, latlon2xy, pairwise_distances, xy2latlog
+from .external_apis import google_distance_matrix, osrm_distance_matrix
+from .factory import get_distance_matrix
+from .haversine import haversine_distance_matrix
+
+__all__ = [
+    "euclidean_distance_matrix",
+    "get_distance_matrix",
+    "google_distance_matrix",
+    "haversine_distance_matrix",
+    "latlon2xy",
+    "osrm_distance_matrix",
+    "pairwise_distances",
+    "xy2latlog",
+]

allocator/distances/euclidean.py

@@ -0,0 +1,80 @@
+"""
+Euclidean distance calculations for geographic coordinates.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import utm
+
+
+def pairwise_distances(X: np.ndarray, Y: np.ndarray | None = None) -> np.ndarray:
+    """Pairwise euclidean distance calculation."""
+    if Y is None:
+        Y = X
+    return np.sqrt(((Y - X[:, np.newaxis]) ** 2).sum(axis=2))
+
+
+def latlon2xy(lat: float, lon: float) -> list[float]:
+    """Transform lat/lon to UTM coordinate
+
+    Args:
+        lat (float): WGS latitude
+        lon (float): WGS longitude
+
+    Returns:
+        [x, y]: UTM x, y coordinate
+
+    """
+    utm_x, utm_y, _, _ = utm.from_latlon(lat, lon)
+
+    return [utm_x, utm_y]
+
+
+def xy2latlog(
+    x: float, y: float, zone_number: int, zone_letter: str | None = None
+) -> tuple[float, float]:
+    """Transform x, y coordinate to lat/lon coordinate
+
+    Args:
+        x (float): UTM x coordinate
+        y (float): UTM y coordinate
+        zone_number (int): UTM zone number
+        zone_letter (str, optional): UTM zone letter. Defaults to None.
+
+    Returns:
+        (lat, lon): WGS latitude, longitude
+
+    """
+    lat, lon = utm.to_latlon(x, y, zone_number, zone_letter)
+
+    return (lat, lon)
+
+
+def euclidean_distance_matrix(
+    points_from: np.ndarray, points_to: np.ndarray | None = None
+) -> np.ndarray:
+    """
+    Calculate euclidean distance matrix between two sets of lat/lon points.
+
+    Args:
+        points_from: Source points (numpy array with shape [n, 2] where columns are [lon, lat])
+        points_to: Destination points (optional, defaults to points_from)
+
+    Returns:
+        Distance matrix as numpy array with shape [len(points_from), len(points_to)]
+    """
+    # Handle empty arrays
+    if len(points_from) == 0:
+        points_to_len = len(points_to) if points_to is not None else 0
+        return np.array([]).reshape(0, points_to_len)
+
+    # Convert lat/lon to UTM coordinates for accurate euclidean distance
+    utm_from = np.array([latlon2xy(lat, lon) for lon, lat in points_from])
+
+    if points_to is None:
+        utm_to = utm_from
+    else:
+        utm_to = np.array([latlon2xy(lat, lon) for lon, lat in points_to])
+
+    return pairwise_distances(utm_from, utm_to)