allocator 1.0.0__tar.gz → 1.2.0__tar.gz

{allocator-1.0.0 → allocator-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allocator
-Version: 1.0.0
+Version: 1.2.0
 Summary: Modern Python package for geographic task allocation, clustering, and routing optimization
 Keywords: geographic,allocation,clustering,routing,optimization,tsp,kmeans,geospatial,logistics,shortest-path
 Author: Suriyan Laohaprapanon, Gaurav Sood
@@ -23,6 +23,7 @@ Classifier: Typing :: Typed
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: numpy>=1.24.0
 Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: scipy>=1.10.0
 Requires-Dist: utm>=0.7.0
 Requires-Dist: haversine>=2.8.0
 Requires-Dist: networkx>=3.0
@@ -33,7 +34,6 @@ Requires-Dist: googlemaps>=4.6.0
 Requires-Dist: ortools>=9.5.0
 Requires-Dist: matplotlib>=3.6.0
 Requires-Dist: seaborn>=0.13.2
-Requires-Dist: scipy>=1.10.0 ; extra == 'algorithms'
 Requires-Dist: christofides>=1.0.0 ; extra == 'algorithms'
 Requires-Dist: allocator[algorithms,geo] ; extra == 'all'
 Requires-Dist: allocator[all,dev,test,docs] ; extra == 'complete'
@@ -58,12 +58,12 @@ Requires-Dist: hypothesis>=6.82.0 ; extra == 'test'
 Maintainer: Gaurav Sood
 Maintainer-email: Gaurav Sood <gsood07@gmail.com>
 Requires-Python: >=3.11
-Project-URL: Bug Reports, https://github.com/geosensing/allocator/issues
-Project-URL: Changelog, https://github.com/geosensing/allocator/blob/main/CHANGELOG.md
-Project-URL: Documentation, https://geosensing.github.io/allocator/
 Project-URL: Homepage, https://github.com/geosensing/allocator
+Project-URL: Documentation, https://geosensing.github.io/allocator/
 Project-URL: Repository, https://github.com/geosensing/allocator.git
+Project-URL: Bug Reports, https://github.com/geosensing/allocator/issues
 Project-URL: Source Code, https://github.com/geosensing/allocator
+Project-URL: Changelog, https://github.com/geosensing/allocator/blob/main/CHANGELOG.md
 Provides-Extra: algorithms
 Provides-Extra: all
 Provides-Extra: complete
@@ -73,60 +73,90 @@ Provides-Extra: geo
 Provides-Extra: test
 Description-Content-Type: text/markdown
 
-# allocator: Efficiently collect data from geographically distributed locations
+# allocator
 
 [![PyPI version](https://img.shields.io/pypi/v/allocator.svg)](https://pypi.python.org/pypi/allocator)
 [![Downloads](https://pepy.tech/badge/allocator)](https://pepy.tech/project/allocator)
 [![CI](https://github.com/geosensing/allocator/actions/workflows/ci.yml/badge.svg)](https://github.com/geosensing/allocator/actions/workflows/ci.yml)
 [![Documentation](https://img.shields.io/badge/docs-github.io-blue)](https://geosensing.github.io/allocator/)
 
-**Allocator** provides a modern, Pythonic API for geographic task allocation, clustering, and routing optimization.
+Field teams, delivery services, and survey organizations waste time and money on inefficient routes. When you have 100+ locations to visit, manual planning fails. Allocator solves this.
 
-## Key Features
+## What It Does
 
-- **🎯 Clustering**: Group geographic points into balanced zones
-- **🛣️ Routing**: Find optimal paths through locations (TSP solving)  
-- **📍 Assignment**: Connect points to closest workers/centers
-- **🚀 Performance**: Optimized algorithms with NumPy and scikit-learn
-- **📦 Modern API**: Clean Python interface + unified CLI
+- **Cluster**: Divide locations into balanced work zones
+- **Route**: Find the shortest path through locations (TSP)
+- **Assign**: Match locations to nearest workers or depots
+- **Random Walk**: Generate survey itineraries on road networks
 
-## Quick Start
+## Install
 
 ```bash
 pip install allocator
 ```
 
+## Python API
+
+### Cluster locations into zones
+
 ```python
 import allocator
 import pandas as pd
 
-# Geographic locations
 locations = pd.DataFrame({
-    'longitude': [100.5018, 100.5065, 100.5108],
-    'latitude': [13.7563, 13.7590, 13.7633]
+    'longitude': [100.501, 100.506, 100.510, 100.515, 100.520],
+    'latitude': [13.756, 13.759, 13.763, 13.768, 13.772]
 })
 
-# Group into zones
-clusters = allocator.cluster(locations, n_clusters=2)
+result = allocator.cluster(locations, n_clusters=2)
+print(result.labels)  # [0 0 0 1 1]
+```
+
+### Find shortest route
+
+```python
+route = allocator.shortest_path(locations, method='ortools')
+print(route.route)  # [0, 1, 2, 4, 3, 0]
+```
 
-# Find optimal route
-route = allocator.shortest_path(locations)
+### Assign to nearest depot
 
-# Assign to service centers
-centers = pd.DataFrame({
+```python
+depots = pd.DataFrame({
     'longitude': [100.50, 100.52],
     'latitude': [13.75, 13.77]
 })
-assignments = allocator.assign(locations, centers)
+
+assignments = allocator.assign_to_closest(locations, depots)
+print(assignments.data['assigned_worker'].tolist())  # [0, 0, 1, 1, 1]
+```
+
+### Generate random walk itineraries
+
+```python
+import networkx as nx
+
+# Load road network graph (from OSMnx or similar)
+G = nx.read_graphml("road_network.graphml")
+
+result = allocator.random_walk(G, n_walks=10, walk_length_m=5000)
+print(result.data)  # DataFrame with waypoints
+```
+
+## CLI
+
+```bash
+allocator cluster kmeans locations.csv -n 5 -o zones.csv
+allocator route tsp locations.csv --method ortools -o route.csv
+allocator sort locations.csv --workers depots.csv -o assignments.csv
+allocator random-walk road_network.graphml -n 10 -l 5000 -o waypoints.csv
 ```
 
-## Documentation & Examples
+## Documentation
 
-- **📖 [Full Documentation](https://geosensing.github.io/allocator/)**
-- **🚀 [Installation & Tutorial](https://geosensing.github.io/allocator/quickstart.html)**  
-- **🔧 [API Reference](https://geosensing.github.io/allocator/api/clustering.html)**
-- **💡 [Real-World Examples](https://geosensing.github.io/allocator/examples/overview.html)**
+- [Full Documentation](https://geosensing.github.io/allocator/)
+- [API Reference](https://geosensing.github.io/allocator/api/clustering.html)
 
-## License & Contributing
+## License
 
-MIT License. Contributions welcome - see [Contributing Guide](https://geosensing.github.io/allocator/contributing.html).
+MIT

allocator-1.2.0/README.md

@@ -0,0 +1,87 @@
+# allocator
+
+[![PyPI version](https://img.shields.io/pypi/v/allocator.svg)](https://pypi.python.org/pypi/allocator)
+[![Downloads](https://pepy.tech/badge/allocator)](https://pepy.tech/project/allocator)
+[![CI](https://github.com/geosensing/allocator/actions/workflows/ci.yml/badge.svg)](https://github.com/geosensing/allocator/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-github.io-blue)](https://geosensing.github.io/allocator/)
+
+Field teams, delivery services, and survey organizations waste time and money on inefficient routes. When you have 100+ locations to visit, manual planning fails. Allocator solves this.
+
+## What It Does
+
+- **Cluster**: Divide locations into balanced work zones
+- **Route**: Find the shortest path through locations (TSP)
+- **Assign**: Match locations to nearest workers or depots
+- **Random Walk**: Generate survey itineraries on road networks
+
+## Install
+
+```bash
+pip install allocator
+```
+
+## Python API
+
+### Cluster locations into zones
+
+```python
+import allocator
+import pandas as pd
+
+locations = pd.DataFrame({
+    'longitude': [100.501, 100.506, 100.510, 100.515, 100.520],
+    'latitude': [13.756, 13.759, 13.763, 13.768, 13.772]
+})
+
+result = allocator.cluster(locations, n_clusters=2)
+print(result.labels)  # [0 0 0 1 1]
+```
+
+### Find shortest route
+
+```python
+route = allocator.shortest_path(locations, method='ortools')
+print(route.route)  # [0, 1, 2, 4, 3, 0]
+```
+
+### Assign to nearest depot
+
+```python
+depots = pd.DataFrame({
+    'longitude': [100.50, 100.52],
+    'latitude': [13.75, 13.77]
+})
+
+assignments = allocator.assign_to_closest(locations, depots)
+print(assignments.data['assigned_worker'].tolist())  # [0, 0, 1, 1, 1]
+```
+
+### Generate random walk itineraries
+
+```python
+import networkx as nx
+
+# Load road network graph (from OSMnx or similar)
+G = nx.read_graphml("road_network.graphml")
+
+result = allocator.random_walk(G, n_walks=10, walk_length_m=5000)
+print(result.data)  # DataFrame with waypoints
+```
+
+## CLI
+
+```bash
+allocator cluster kmeans locations.csv -n 5 -o zones.csv
+allocator route tsp locations.csv --method ortools -o route.csv
+allocator sort locations.csv --workers depots.csv -o assignments.csv
+allocator random-walk road_network.graphml -n 10 -l 5000 -o waypoints.csv
+```
+
+## Documentation
+
+- [Full Documentation](https://geosensing.github.io/allocator/)
+- [API Reference](https://geosensing.github.io/allocator/api/clustering.html)
+
+## License
+
+MIT

{allocator-1.0.0 → allocator-1.2.0}/allocator/__init__.py

@@ -34,17 +34,25 @@ For more examples: https://geosensing.github.io/allocator/
 
 import logging
 import sys
+import warnings
+
+warnings.filterwarnings("ignore", message=".*SwigPyPacked.*")
+warnings.filterwarnings("ignore", message=".*SwigPyObject.*")
+warnings.filterwarnings("ignore", message=".*swigvarlink.*")
 
-# Import modern API
 from .api import (
     ClusterResult,
     ComparisonResult,
+    ItineraryResult,
+    RandomWalkResult,
     RouteResult,
     SortResult,
     assign_to_closest,
     cluster,
+    create_itineraries,
     distance_assignment,
     kmeans,
+    random_walk,
     shortest_path,
     sort_by_distance,
     tsp_christofides,
@@ -52,8 +60,6 @@ from .api import (
     tsp_ortools,
     tsp_osrm,
 )
-
-# Import utilities for advanced users
 from .distances import (
     euclidean_distance_matrix,
     get_distance_matrix,
@@ -63,26 +69,25 @@ from .distances import (
     osrm_distance_matrix,
     xy2latlog,
 )
-
-# Import visualization functions
 from .viz.plotting import plot_assignments, plot_clusters, plot_comparison, plot_route
 
-# Version
-__version__ = "1.0.0"
+__version__ = "1.2.0"
 
-# Export public API
 __all__ = [
     # Result types
     "ClusterResult",
     "ComparisonResult",
+    "ItineraryResult",
+    "RandomWalkResult",
     "RouteResult",
     "SortResult",
-    "assign_to_closest",
     # Main functions
+    "assign_to_closest",
     "cluster",
+    "create_itineraries",
     "distance_assignment",
-    "euclidean_distance_matrix",
     # Distance utilities
+    "euclidean_distance_matrix",
     "get_distance_matrix",
     "get_logger",
     "google_distance_matrix",
@@ -91,11 +96,13 @@ __all__ = [
     "kmeans",
     "latlon2xy",
     "osrm_distance_matrix",
-    "plot_assignments",
     # Visualization
+    "plot_assignments",
     "plot_clusters",
     "plot_comparison",
     "plot_route",
+    # Random walk
+    "random_walk",
     # Logging utilities
     "setup_logging",
     "shortest_path",
@@ -108,27 +115,23 @@ __all__ = [
 ]
 
 
-def setup_logging(level=logging.INFO):
+def setup_logging(level: int = logging.INFO) -> logging.Logger:
     """
     Set up logging configuration for the allocator package.
 
     Args:
         level: Logging level (DEBUG, INFO, WARNING, ERROR)
     """
-    # Create formatter
     formatter = logging.Formatter(
         "%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S"
     )
 
-    # Get root logger for allocator package
     logger = logging.getLogger("allocator")
     logger.setLevel(level)
 
-    # Remove existing handlers to avoid duplicates
     for handler in logger.handlers[:]:
         logger.removeHandler(handler)
 
-    # Console handler
     console_handler = logging.StreamHandler(sys.stdout)
     console_handler.setLevel(level)
     console_handler.setFormatter(formatter)
@@ -137,7 +140,7 @@ def setup_logging(level=logging.INFO):
     return logger
 
 
-def get_logger(name):
+def get_logger(name: str) -> logging.Logger:
     """
     Get a logger instance for a specific module.
 
@@ -150,5 +153,4 @@ def get_logger(name):
     return logging.getLogger(f"allocator.{name}")
 
 
-# Set up default logging
 setup_logging()

{allocator-1.0.0 → allocator-1.2.0}/allocator/api/__init__.py

@@ -6,22 +6,36 @@ This module provides a modern, Pythonic interface to the allocator package.
 
 from .cluster import cluster, kmeans
 from .distance import assign_to_closest, distance_assignment, sort_by_distance
+from .itinerary import create_itineraries
+from .random_walk import random_walk
 from .route import shortest_path, tsp_christofides, tsp_google, tsp_ortools, tsp_osrm
-from .types import ClusterResult, ComparisonResult, RouteResult, SortResult
+from .types import (
+    ClusterResult,
+    ComparisonResult,
+    ItineraryResult,
+    RandomWalkResult,
+    RouteResult,
+    SortResult,
+)
 
 __all__ = [
     # Result types
     "ClusterResult",
     "ComparisonResult",
+    "ItineraryResult",
+    "RandomWalkResult",
     "RouteResult",
     "SortResult",
     # Distance assignment methods
     "assign_to_closest",
     # Main high-level functions
     "cluster",
+    "create_itineraries",
     "distance_assignment",
     # Specific clustering methods
     "kmeans",
+    # Random walk
+    "random_walk",
     "shortest_path",
     "sort_by_distance",
     # Specific routing methods

{allocator-1.0.0 → allocator-1.2.0}/allocator/api/cluster.py

@@ -2,8 +2,6 @@
 Modern clustering API for allocator package.
 """
 
-from __future__ import annotations
-
 from pathlib import Path
 
 import numpy as np
@@ -66,15 +64,16 @@ def kmeans(
     Args:
         data: Input data as DataFrame or numpy array
         n_clusters: Number of clusters
-        distance: Distance metric ('euclidean', 'haversine', 'osrm', 'google')
+        distance: Distance metric (stored in metadata only; clustering uses Euclidean)
         max_iter: Maximum iterations
         random_state: Random seed for reproducibility
-        **kwargs: Additional distance-specific arguments
+        **kwargs: Additional arguments (unused, kept for API compatibility)
 
     Returns:
         ClusterResult with clustering information
     """
-    # Ensure we have a DataFrame for output
+    del kwargs
+
     if isinstance(data, np.ndarray):
         df = DataHandler._from_numpy(data)
     elif isinstance(data, list):
@@ -84,36 +83,21 @@ def kmeans(
     else:
         df = data.copy()
 
-    # Run clustering algorithm
     result = _kmeans_cluster(
         df,
         n_clusters=n_clusters,
-        distance_method=distance,
         max_iter=max_iter,
         random_state=random_state,
-        **kwargs,
     )
 
-    # Add cluster assignments to DataFrame
     df_result = df.copy()
     df_result["cluster"] = result["labels"]
 
-    # Calculate inertia (sum of squared distances to centroids)
-    inertia = None
-    if distance == "euclidean":
-        from ..distances import euclidean_distance_matrix
-
-        coords = df[["longitude", "latitude"]].values
-        distances = euclidean_distance_matrix(coords, result["centroids"])
-        inertia = np.sum(
-            [distances[i, result["labels"][i]] ** 2 for i in range(len(result["labels"]))]
-        )
-
     return ClusterResult(
         labels=result["labels"],
         centroids=result["centroids"],
         n_iter=result["iterations"],
-        inertia=inertia,
+        inertia=result["inertia"],
         data=df_result,
         converged=result["converged"],
         metadata={

{allocator-1.0.0 → allocator-1.2.0}/allocator/api/distance.py

@@ -2,8 +2,6 @@
 Modern distance-based assignment API for allocator package.
 """
 
-from __future__ import annotations
-
 import numpy as np
 import pandas as pd
 

allocator-1.2.0/allocator/api/itinerary.py

@@ -0,0 +1,185 @@
+"""
+API for itinerary generation.
+"""
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from ..core.itinerary import (
+    greedy_grow_itineraries,
+    kmeans_tsp_itineraries,
+    random_partition_itineraries,
+    round_robin_itineraries,
+    softmax_greedy_itineraries,
+    stratified_itineraries,
+)
+from ..distances import get_distance_matrix
+from ..io.data_handler import DataHandler
+from .types import BUDGET_METHODS, PARTITION_METHODS, VALID_METHODS, ItineraryResult
+
+
+def create_itineraries(
+    data: str | pd.DataFrame | np.ndarray | list[Any],
+    max_distance: float | None = None,
+    n_itineraries: int | None = None,
+    method: str = "greedy_nn",
+    distance: str = "haversine",
+    start_method: str = "random",
+    temperature: float = 0.1,
+    n_strata: int = 4,
+    optimize_routes: bool = True,
+    seed: int | None = None,
+    **kwargs: Any,
+) -> ItineraryResult:
+    """
+    Create multiple itineraries from points with a distance budget per itinerary.
+
+    Args:
+        data: Input data (file path, DataFrame, numpy array, or list)
+        max_distance: Maximum total distance per itinerary (in meters for haversine/osrm/google).
+            Required for greedy_nn and softmax_greedy methods.
+        n_itineraries: Number of itineraries to create. Required for random_partition,
+            stratified, round_robin, and kmeans_tsp methods.
+        method: Itinerary generation method:
+            - "greedy_nn": Greedy nearest-neighbor (default, most efficient)
+            - "random_partition": Random assignment (theoretical baseline)
+            - "stratified": Stratified by distance from centroid
+            - "round_robin": Round-robin assignment
+            - "softmax_greedy": Greedy with softmax sampling
+            - "kmeans_tsp": K-means clustering with TSP optimization
+        distance: Distance metric ('euclidean', 'haversine', 'osrm', 'google')
+        start_method: How to pick starting point for greedy methods
+            - "random": Random unvisited point
+            - "furthest": Point furthest from centroid of remaining points
+            - "first": First available unvisited point (index order)
+        temperature: Softmax temperature for softmax_greedy method (default 0.1)
+        n_strata: Number of strata for stratified method (default 4)
+        optimize_routes: Whether to TSP-optimize routes for partition methods (default True)
+        seed: Random seed for reproducibility
+        **kwargs: Additional arguments for distance calculation:
+            - api_key: Required for 'google' distance
+            - osrm_base_url: Custom OSRM server URL
+
+    Returns:
+        ItineraryResult containing:
+            - itineraries: List of routes (each route is list of point indices)
+            - distances: Total distance for each itinerary
+            - data: Original DataFrame with itinerary_id column added
+            - metadata: Algorithm details
+
+    Example:
+        >>> result = create_itineraries('points.csv', max_distance=20000, method='greedy_nn')
+        >>> result = create_itineraries('points.csv', n_itineraries=10, method='random_partition')
+    """
+    if method not in VALID_METHODS:
+        raise ValueError(f"Unknown method: {method}. Use one of {VALID_METHODS}")
+
+    if method in BUDGET_METHODS and max_distance is None:
+        raise ValueError(f"max_distance is required for method '{method}'")
+    if method in PARTITION_METHODS and n_itineraries is None:
+        raise ValueError(f"n_itineraries is required for method '{method}'")
+
+    df = DataHandler.load_data(data)
+
+    if len(df) == 0:
+        return ItineraryResult(
+            itineraries=[],
+            distances=[],
+            data=df.assign(itinerary_id=[]),
+            metadata={
+                "n_points": 0,
+                "n_itineraries": 0,
+                "max_distance": max_distance,
+                "method": method,
+                "distance": distance,
+            },
+        )
+
+    points: np.ndarray = df[["longitude", "latitude"]].to_numpy()
+    distance_matrix = get_distance_matrix(points, points, method=distance, **kwargs)
+
+    rng = np.random.default_rng(seed)
+
+    itineraries: list[list[int]]
+    distances: list[float]
+
+    if method == "greedy_nn":
+        itineraries, distances = greedy_grow_itineraries(
+            distance_matrix,
+            max_distance=max_distance,  # type: ignore[arg-type]
+            start_method=start_method,
+            rng=rng,
+        )
+    elif method == "random_partition":
+        itineraries, distances = random_partition_itineraries(
+            distance_matrix,
+            n_itineraries=n_itineraries,  # type: ignore[arg-type]
+            optimize_routes=optimize_routes,
+            rng=rng,
+        )
+    elif method == "stratified":
+        itineraries, distances = stratified_itineraries(
+            distance_matrix,
+            points=points,
+            n_itineraries=n_itineraries,  # type: ignore[arg-type]
+            n_strata=n_strata,
+            optimize_routes=optimize_routes,
+            rng=rng,
+        )
+    elif method == "round_robin":
+        itineraries, distances = round_robin_itineraries(
+            distance_matrix,
+            n_itineraries=n_itineraries,  # type: ignore[arg-type]
+            optimize_routes=optimize_routes,
+            rng=rng,
+        )
+    elif method == "softmax_greedy":
+        itineraries, distances = softmax_greedy_itineraries(
+            distance_matrix,
+            max_distance=max_distance,  # type: ignore[arg-type]
+            temperature=temperature,
+            start_method=start_method,
+            rng=rng,
+        )
+    else:
+        itineraries, distances = kmeans_tsp_itineraries(
+            distance_matrix,
+            points=points,
+            n_itineraries=n_itineraries,  # type: ignore[arg-type]
+            max_distance=max_distance,
+            rng=rng,
+        )
+
+    itinerary_ids = np.full(len(df), -1, dtype=int)
+    for itinerary_idx, route in enumerate(itineraries):
+        for point_idx in route:
+            itinerary_ids[point_idx] = itinerary_idx
+
+    result_df = df.copy()
+    result_df["itinerary_id"] = itinerary_ids
+
+    return ItineraryResult(
+        itineraries=itineraries,
+        distances=distances,
+        data=result_df,
+        metadata={
+            "n_points": len(df),
+            "n_itineraries": len(itineraries),
+            "max_distance": max_distance,
+            "n_itineraries_requested": n_itineraries,
+            "method": method,
+            "distance": distance,
+            "start_method": start_method if method in BUDGET_METHODS else None,
+            "temperature": temperature if method == "softmax_greedy" else None,
+            "n_strata": n_strata if method == "stratified" else None,
+            "optimize_routes": optimize_routes if method in PARTITION_METHODS else None,
+            "seed": seed,
+            "total_distance": float(sum(distances)) if distances else 0.0,
+            "avg_distance": float(np.mean(distances)) if distances else 0.0,
+            "avg_points_per_itinerary": (
+                float(np.mean([len(it) for it in itineraries])) if itineraries else 0.0
+            ),
+        },
+    )