mamut-routing-tools 0.1.0__tar.gz

mamut_routing_tools-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python tooling outputs
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+build/
+.venv/
+.python-version
+
+# Local OSM stores and derived caches (workspace data, never tracked)
+/osmdata/
+/graph-cache/
+/workspaces/

mamut_routing_tools-0.1.0/CITATION.cff

@@ -0,0 +1,51 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: MAMUT-routing-tools
+message: >-
+  If you use MAMUT-routing-tools, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Florian
+    family-names: Rascoussier
+    alias: Onyr
+    affiliation: IMT Atlantique; INSA Lyon
+    orcid: "https://orcid.org/0009-0005-3253-9814"
+  - given-names: Adrien
+    family-names: Pichon
+    alias: Anzury
+    affiliation: Université Bretagne Sud
+    orcid: "https://orcid.org/0009-0005-8630-3962"
+repository-code: "https://github.com/ANR-MAMUT/MAMUT-routing-tools"
+abstract: >-
+  MAMUT-routing-tools is the local generation tool suite of the
+  MAMUT-routing benchmark project: OpenStreetMap city acquisition,
+  a road-graph engine compatible with the project's published
+  OSM-derived benchmark data, best-known-solution route-geometry
+  materialization, and interactive CVRP/VRPTW instance generation.
+  It complements the MAMUT-routing benchmark repository and its
+  static website by running all compute-heavy workflows locally,
+  supporting reproducible computational experiments in Operations
+  Research, Computer Science, and Applied Algorithmics.
+keywords:
+  - benchmarking
+  - CVRP
+  - VRPTW
+  - reproducibility
+  - vehicle routing problem
+  - instance generation
+  - best-known solutions
+  - BKS
+  - open science
+  - optimization benchmarks
+  - OpenStreetMap
+  - OSM
+  - road network
+  - urban logistics
+  - research software
+  - routing
+license: MIT
+version: 0.1.0
+date-released: "2026-07-18"

mamut_routing_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ANR-MAMUT
+
+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.

mamut_routing_tools-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: mamut-routing-tools
+Version: 0.1.0
+Summary: Local generation tool suite for MAMUT-routing: OSM acquisition, road-graph engine, route geometry, and CVRP/VRPTW instance generation.
+Project-URL: Repository, https://github.com/ANR-MAMUT/MAMUT-routing-tools
+Project-URL: Website, https://mamut-routing.univ-ubs.fr/
+Author: Adrien Pichon
+Author-email: Florian Rascoussier <onyr.maintainer@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: CVRP,OSM,OpenStreetMap,VRP,VRPTW,benchmarking,instance generation,operations research,road network,vehicle routing problem
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mamut-routing-lib
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rustworkx>=0.15
+Requires-Dist: scipy>=1.13
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# MAMUT-routing-tools
+
+Local generation tool suite for the [MAMUT-routing](https://github.com/ANR-MAMUT/MAMUT-routing) benchmark project: OSM city acquisition, a road-graph engine, BKS route-geometry materialization, and interactive CVRP/VRPTW instance generation. The public MAMUT-routing website is fully static; everything compute-heavy lives here and runs on your own machine.
+
+Part of the [ANR MAMUT project](https://mamut.roadef.org/).
+
+## Status
+
+Beta. The tool suite is being extracted from the website's former Julia backend; interfaces may change between releases.
+
+## Components
+
+- `mamut-tools roadgraph`: build and inspect drivable road graphs from OSM XML extracts. The construction is a faithful Python port of the OpenStreetMapX.jl pipeline the project previously used (same road classes, oneway rules, intersection segmentation, ENU distances, and strongly-connected trim), so graphs and route geometry stay consistent with previously published data.
+- `mamut-tools geometry`: materialize road-following polylines for best-known solutions, in the exact artifact format the MAMUT-routing website consumes.
+- Planned: OSM city fetch (Nominatim + Overpass), interactive CVRP/VRPTW generation with a local workbench GUI, and the official time-dependent benchmark campaign pipeline.
+
+## Install
+
+Requires Python >= 3.11 and [uv](https://github.com/astral-sh/uv).
+
+```bash
+git clone --recurse-submodules https://github.com/ANR-MAMUT/MAMUT-routing-tools.git
+cd MAMUT-routing-tools
+uv sync
+uv run mamut-tools --help
+```
+
+The `MAMUT-routing-lib` contract library is vendored as a git submodule and installed as an editable dependency.
+
+## Quick examples
+
+```bash
+# Road-graph statistics for a city extract
+uv run mamut-tools roadgraph info path/to/City.osm
+
+# Materialize a route-geometry group plan (website build contract)
+uv run mamut-tools geometry materialize-plan plan.json --repo-root path/to/MAMUT-routing --result-dir out/
+```

mamut_routing_tools-0.1.0/README.md

@@ -0,0 +1,38 @@
+# MAMUT-routing-tools
+
+Local generation tool suite for the [MAMUT-routing](https://github.com/ANR-MAMUT/MAMUT-routing) benchmark project: OSM city acquisition, a road-graph engine, BKS route-geometry materialization, and interactive CVRP/VRPTW instance generation. The public MAMUT-routing website is fully static; everything compute-heavy lives here and runs on your own machine.
+
+Part of the [ANR MAMUT project](https://mamut.roadef.org/).
+
+## Status
+
+Beta. The tool suite is being extracted from the website's former Julia backend; interfaces may change between releases.
+
+## Components
+
+- `mamut-tools roadgraph`: build and inspect drivable road graphs from OSM XML extracts. The construction is a faithful Python port of the OpenStreetMapX.jl pipeline the project previously used (same road classes, oneway rules, intersection segmentation, ENU distances, and strongly-connected trim), so graphs and route geometry stay consistent with previously published data.
+- `mamut-tools geometry`: materialize road-following polylines for best-known solutions, in the exact artifact format the MAMUT-routing website consumes.
+- Planned: OSM city fetch (Nominatim + Overpass), interactive CVRP/VRPTW generation with a local workbench GUI, and the official time-dependent benchmark campaign pipeline.
+
+## Install
+
+Requires Python >= 3.11 and [uv](https://github.com/astral-sh/uv).
+
+```bash
+git clone --recurse-submodules https://github.com/ANR-MAMUT/MAMUT-routing-tools.git
+cd MAMUT-routing-tools
+uv sync
+uv run mamut-tools --help
+```
+
+The `MAMUT-routing-lib` contract library is vendored as a git submodule and installed as an editable dependency.
+
+## Quick examples
+
+```bash
+# Road-graph statistics for a city extract
+uv run mamut-tools roadgraph info path/to/City.osm
+
+# Materialize a route-geometry group plan (website build contract)
+uv run mamut-tools geometry materialize-plan plan.json --repo-root path/to/MAMUT-routing --result-dir out/
+```

mamut_routing_tools-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "mamut-routing-tools"
+version = "0.1.0"
+description = "Local generation tool suite for MAMUT-routing: OSM acquisition, road-graph engine, route geometry, and CVRP/VRPTW instance generation."
+readme = "README.md"
+authors = [
+    { name = "Florian Rascoussier", email = "onyr.maintainer@gmail.com" },
+    { name = "Adrien Pichon" },
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "vehicle routing problem",
+    "VRP",
+    "CVRP",
+    "VRPTW",
+    "benchmarking",
+    "instance generation",
+    "OpenStreetMap",
+    "OSM",
+    "road network",
+    "operations research",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "mamut-routing-lib",
+    "typer>=0.12",
+    "pydantic>=2.7",
+    "numpy>=1.26",
+    "scipy>=1.13",
+    "rustworkx>=0.15",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Repository = "https://github.com/ANR-MAMUT/MAMUT-routing-tools"
+Website = "https://mamut-routing.univ-ubs.fr/"
+
+[project.scripts]
+mamut-tools = "mamut_routing_tools.cli:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mamut_routing_tools"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    ".git",
+    ".gitignore",
+    ".gitmodules",
+    ".github",
+    "MAMUT-routing-lib",
+    "nix-dev",
+    "tests",
+    "uv.lock",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mamut_routing_tools-0.1.0/src/mamut_routing_tools/__init__.py

@@ -0,0 +1,4 @@
+"""MAMUT-routing-tools: local OSM acquisition, road-graph engine, route
+geometry, and instance generation for the MAMUT-routing benchmark project."""
+
+__version__ = "0.1.0"

mamut_routing_tools-0.1.0/src/mamut_routing_tools/cli.py

@@ -0,0 +1,103 @@
+"""mamut-tools: command-line interface of MAMUT-routing-tools."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+app = typer.Typer(
+    name="mamut-tools",
+    help="Local MAMUT-routing tool suite: OSM acquisition, road-graph engine, route geometry, and instance generation.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+roadgraph_app = typer.Typer(help="Road-graph engine (OpenStreetMapX-compatible construction).", no_args_is_help=True)
+geometry_app = typer.Typer(help="BKS route-geometry materialization.", no_args_is_help=True)
+osm_app = typer.Typer(help="OSM city acquisition (Nominatim + Overpass).", no_args_is_help=True)
+app.add_typer(roadgraph_app, name="roadgraph")
+app.add_typer(geometry_app, name="geometry")
+app.add_typer(osm_app, name="osm")
+
+
+@osm_app.command("fetch-city")
+def osm_fetch_city_cmd(
+    city: Annotated[str, typer.Argument(help="City or locality name to geocode and download.")],
+    country: Annotated[str, typer.Option("--country", help="Optional country to disambiguate the geocode.")] = "",
+    osm_dir: Annotated[Path, typer.Option("--osm-dir", help="Directory for the downloaded <city>.osm extract.")] = Path("osmdata"),
+    padding_km: Annotated[float, typer.Option("--padding-km", help="Extra bbox padding in km.")] = 0.0,
+    max_radius_km: Annotated[float, typer.Option("--max-radius-km", help="Clamp the administrative bbox to a square of this radius around the place's geocode point (0 = no clamp).")] = 0.0,
+) -> None:
+    """Download an OSM extract (roads + amenities) for a city by name."""
+    from mamut_routing_tools.osm import fetch_and_store_city_osm
+
+    summary = fetch_and_store_city_osm(
+        city,
+        country=country,
+        osm_dir=osm_dir,
+        padding_km=padding_km,
+        max_radius_km=max_radius_km,
+    )
+    typer.echo(json.dumps(summary, indent=1))
+
+
+@roadgraph_app.command("info")
+def roadgraph_info_cmd(
+    osm_path: Annotated[Path, typer.Argument(help="OSM XML extract to build the road graph from.")],
+    only_intersections: Annotated[bool, typer.Option("--only-intersections/--all-nodes")] = True,
+    trim_to_connected: Annotated[bool, typer.Option("--trim/--no-trim")] = True,
+) -> None:
+    """Build the road graph and print vertex/edge statistics."""
+    from mamut_routing_tools.roadgraph import load_road_graph
+
+    graph = load_road_graph(
+        osm_path,
+        only_intersections=only_intersections,
+        trim_to_connected=trim_to_connected,
+    )
+    class_counts: dict[int, int] = {}
+    for cls in graph.edge_class:
+        class_counts[cls] = class_counts.get(cls, 0) + 1
+    typer.echo(
+        json.dumps(
+            {
+                "osm_path": str(graph.osm_path),
+                "only_intersections": graph.only_intersections,
+                "trim_to_connected": graph.trim_to_connected,
+                "vertices": graph.vertex_count,
+                "edges": graph.edge_count,
+                "total_edge_length_km": round(sum(graph.edge_weight) / 1000.0, 3),
+                "edge_class_counts": {str(k): class_counts[k] for k in sorted(class_counts)},
+                "ref_lla": {"lat": graph.ref_lla.lat, "lon": graph.ref_lla.lon},
+            },
+            indent=1,
+        )
+    )
+
+
+@geometry_app.command("materialize-plan")
+def geometry_materialize_plan_cmd(
+    plan_path: Annotated[Path, typer.Argument(help="Group plan JSON (route_geometry.py contract).")],
+    repo_root: Annotated[Path, typer.Option("--repo-root", help="MAMUT-routing repo root the plan paths are relative to.")],
+    result_dir: Annotated[Optional[Path], typer.Option("--result-dir", help="Directory for per-group result files. Prints to stdout when omitted.")] = None,
+) -> None:
+    """Materialize a route-geometry group plan (website build contract)."""
+    from mamut_routing_tools.geometry import materialize_plan
+
+    plan = json.loads(plan_path.read_text(encoding="utf-8"))
+    results = materialize_plan(repo_root, plan)
+    if result_dir is None:
+        typer.echo(json.dumps(results, sort_keys=True))
+        return
+    result_dir.mkdir(parents=True, exist_ok=True)
+    for result_file, payload in results.items():
+        target = result_dir / result_file
+        target.write_text(json.dumps(payload, sort_keys=True, separators=(",", ":")), encoding="utf-8")
+        typer.echo(str(target))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

mamut_routing_tools-0.1.0/src/mamut_routing_tools/geo.py

@@ -0,0 +1,110 @@
+"""Geodetic conversions matching OpenStreetMapX.jl exactly.
+
+The Julia pipeline stores road nodes as ENU coordinates linearized around the
+center of the OSM bounds, computes edge lengths as 3D Euclidean distances in
+that frame, and converts back to LLA for polylines. The Python engine keeps
+the same math so graph weights and rendered coordinates agree to floating
+point noise rather than to a model difference.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import NamedTuple
+
+WGS84_A = 6378137.0
+WGS84_B = 6356752.31424518
+WGS84_E2 = 1.0 - (WGS84_B * WGS84_B) / (WGS84_A * WGS84_A)
+WGS84_EP2 = (WGS84_A * WGS84_A) / (WGS84_B * WGS84_B) - 1.0
+
+
+class LLA(NamedTuple):
+    lat: float
+    lon: float
+    alt: float = 0.0
+
+
+class ECEF(NamedTuple):
+    x: float
+    y: float
+    z: float
+
+
+class ENU(NamedTuple):
+    east: float
+    north: float
+    up: float
+
+
+def ecef_from_lla(lla: LLA) -> ECEF:
+    lat_rad = math.radians(lla.lat)
+    lon_rad = math.radians(lla.lon)
+    sin_lat, cos_lat = math.sin(lat_rad), math.cos(lat_rad)
+    sin_lon, cos_lon = math.sin(lon_rad), math.cos(lon_rad)
+    n = WGS84_A / math.sqrt(1.0 - WGS84_E2 * sin_lat * sin_lat)
+    return ECEF(
+        (n + lla.alt) * cos_lat * cos_lon,
+        (n + lla.alt) * cos_lat * sin_lon,
+        (n * (1.0 - WGS84_E2) + lla.alt) * sin_lat,
+    )
+
+
+def lla_from_ecef(ecef: ECEF) -> LLA:
+    x, y, z = ecef
+    p = math.hypot(x, y)
+    theta = math.atan2(z * WGS84_A, p * WGS84_B)
+    lon = math.atan2(y, x)
+    lat = math.atan2(
+        z + WGS84_EP2 * WGS84_B * math.sin(theta) ** 3,
+        p - WGS84_E2 * WGS84_A * math.cos(theta) ** 3,
+    )
+    n = WGS84_A / math.sqrt(1.0 - WGS84_E2 * math.sin(lat) ** 2)
+    alt = p / math.cos(lat) - n
+    return LLA(math.degrees(lat), math.degrees(lon), alt)
+
+
+def enu_from_lla(lla: LLA, ref: LLA) -> ENU:
+    ecef = ecef_from_lla(lla)
+    ecef_ref = ecef_from_lla(ref)
+    dx, dy, dz = ecef.x - ecef_ref.x, ecef.y - ecef_ref.y, ecef.z - ecef_ref.z
+    lat_rad = math.radians(ref.lat)
+    lon_rad = math.radians(ref.lon)
+    sin_lat, cos_lat = math.sin(lat_rad), math.cos(lat_rad)
+    sin_lon, cos_lon = math.sin(lon_rad), math.cos(lon_rad)
+    east = -sin_lon * dx + cos_lon * dy
+    north = -cos_lon * sin_lat * dx - sin_lon * sin_lat * dy + cos_lat * dz
+    up = cos_lon * cos_lat * dx + sin_lon * cos_lat * dy + sin_lat * dz
+    return ENU(east, north, up)
+
+
+def lla_from_enu(enu: ENU, ref: LLA) -> LLA:
+    lat_rad = math.radians(ref.lat)
+    lon_rad = math.radians(ref.lon)
+    sin_lat, cos_lat = math.sin(lat_rad), math.cos(lat_rad)
+    sin_lon, cos_lon = math.sin(lon_rad), math.cos(lon_rad)
+    east, north, up = enu
+    dx = -sin_lon * east - cos_lon * sin_lat * north + cos_lon * cos_lat * up
+    dy = cos_lon * east - sin_lon * sin_lat * north + sin_lon * cos_lat * up
+    dz = cos_lat * north + sin_lat * up
+    ecef_ref = ecef_from_lla(ref)
+    return lla_from_ecef(ECEF(ecef_ref.x + dx, ecef_ref.y + dy, ecef_ref.z + dz))
+
+
+def enu_distance(a: ENU, b: ENU) -> float:
+    return math.sqrt((b.east - a.east) ** 2 + (b.north - a.north) ** 2 + (b.up - a.up) ** 2)
+
+
+def bounds_center(min_lat: float, min_lon: float, max_lat: float, max_lon: float) -> LLA:
+    lon_mid = (min_lon + max_lon) / 2.0
+    lat_mid = (min_lat + max_lat) / 2.0
+    if min_lon > max_lon:
+        lon_mid = lon_mid - 180.0 if lon_mid > 0 else lon_mid + 180.0
+    return LLA(lat_mid, lon_mid)
+
+
+def haversine_m(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    r = 6371000.0
+    dlat = math.radians(lat2 - lat1)
+    dlon = math.radians(lon2 - lon1)
+    a = math.sin(dlat / 2.0) ** 2 + math.cos(math.radians(lat1)) * math.cos(math.radians(lat2)) * math.sin(dlon / 2.0) ** 2
+    return 2.0 * r * math.asin(math.sqrt(a))

mamut_routing_tools-0.1.0/src/mamut_routing_tools/geometry/__init__.py

@@ -0,0 +1,3 @@
+from mamut_routing_tools.geometry.materialize import materialize_plan
+
+__all__ = ["materialize_plan"]