PyRCH 0.1.0__cp310-cp310-win_amd64.whl

pyrch-0.1.0.dist-info/METADATA

@@ -0,0 +1,444 @@
+Metadata-Version: 2.2
+Name: PyRCH
+Version: 0.1.0
+Summary: RCH: Partial-Expansion Anytime Focal Search solver for heterogeneous multi-agent TSP
+Keywords: mtsp,tsp,multi-agent,path-planning,routing,heterogeneous-agents
+Author: MTSP-Solver Team
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: C++
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Operating System :: POSIX :: Linux
+Project-URL: Homepage, https://github.com/rap-lab-org/dev_peaf
+Project-URL: Repository, https://github.com/rap-lab-org/dev_peaf
+Project-URL: Issues, https://github.com/rap-lab-org/dev_peaf/issues
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.8; extra == "viz"
+Description-Content-Type: text/markdown
+
+# RCH Solver
+
+**RCH** — a solver for the **Heterogeneous Multi-Agent Travelling Salesman Problem (MTSP)**.
+
+This package wraps the high-performance C++ solver core via [pybind11](https://github.com/pybind/pybind11) and makes it available as a regular Python library.
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Python >= 3.8
+- A C++17 compiler (`g++ >= 7`, `clang++ >= 5`)
+- CMake >= 3.15
+- pip
+- matplotlib (only needed for visualization helpers)
+
+### Install from PyPI
+
+```bash
+pip install PyRCH
+```
+
+If you also want plotting helpers:
+
+```bash
+pip install "PyRCH[viz]"
+```
+
+### Install from source
+
+```bash
+cd MTSP-Solver
+
+# Install (builds the C++ extension automatically)
+pip install .
+
+# Or, for development (editable install):
+pip install -e .
+```
+
+> **Note**: On Ubuntu 24+ managed Python installs, you may need to add `--break-system-packages` or use a virtual environment.
+
+## Release To PyPI
+
+If you are publishing manually from a Linux development machine, upload the **sdist** only:
+
+```bash
+python -m build --sdist
+twine check dist/*
+twine upload dist/pyrch-*.tar.gz
+```
+
+> **Why not upload the local wheel?** A wheel built locally on Linux is typically tagged like `linux_x86_64` or `linux_aarch64`. PyPI rejects those platform tags. Linux wheels uploaded to PyPI should be built as compliant `manylinux` wheels, which this repository produces through GitHub Actions.
+
+To publish wheels:
+
+1. Configure PyPI Trusted Publishing for this repository.
+2. Push a version tag such as `v1.0.0`.
+3. Let `.github/workflows/publish-pypi.yml` build and upload the wheels plus sdist.
+
+---
+
+## Quick Start
+
+### 1. Solve a JSON problem file
+
+```python
+import rch
+
+result = rch.solve("path/to/problem.json", time_limit=10)
+
+print(result["status"])        # "success" or "failed"
+print(result["timeout"])       # True if time-limit was reached
+print(result["statistics"])    # {"max_cost": ..., "sum_cost": ..., "solve_time": ..., ...}
+
+for route in result["routes"]:
+    print(f"Agent {route['agent_id']}: path={route['path']}, cost={route['cost']}")
+
+# Anytime improvement history
+for snapshot in result["anytime"]:
+    print(f"  t={snapshot['time']:.3f}s  max_cost={snapshot['max_cost']:.2f}")
+```
+
+### 2. Solve from a Python dict
+
+```python
+import rch
+
+problem_data = {
+    "nodes": [
+        {"id": 0, "x": 0.0, "y": 0.0, "type": "depot"},
+        {"id": 1, "x": 1.0, "y": 2.0, "type": "target"},
+        {"id": 2, "x": 3.0, "y": 1.0, "type": "target"},
+    ],
+    "agents": [
+        {"id": 0, "type": "UAV", "start_node": 0, "end_node": 0},
+        {"id": 1, "type": "UAV", "start_node": 0, "end_node": 0},
+    ],
+    "costs": {
+        "UAV": [
+            [0.0, 2.24, 3.16],
+            [2.24, 0.0, 2.24],
+            [3.16, 2.24, 0.0],
+        ]
+    },
+    "options": {
+        "return_to_end": True,
+        "objective": "min_max"
+    }
+}
+
+result = rch.solve(problem_data, time_limit=5)
+print(result)
+```
+
+### 3. Planner API (recommended)
+
+```python
+import rch
+
+planner = rch.Planner()
+
+# Add nodes
+planner.add_depot(0, x=0.0, y=0.0)
+planner.add_target(1, x=1.0, y=2.0)
+planner.add_target(2, x=3.0, y=1.0)
+
+# Add agents
+planner.add_agent(agent_id=0, agent_type="UAV", start_node=0, end_node=0, time_limit=6.0)
+planner.add_agent(agent_id=1, agent_type="UGV", start_node=0, end_node=0, time_limit=9.0)
+
+# Set cost matrices (one per agent type)
+planner.set_cost_matrix("UAV", [
+    [0.0, 2.24, 3.16],
+    [2.24, 0.0, 2.24],
+    [3.16, 2.24, 0.0],
+])
+planner.set_cost_matrix("UGV", [
+    [0.0, 1.80, 4.20],
+    [1.80, 0.0, 2.90],
+    [4.20, 2.90, 0.0],
+])
+
+# Add constraints (optional)
+planner.add_assignment(1, ["UAV"])
+planner.add_assignment(2, ["UGV"])
+planner.add_time_window(1, start=0.0, end=3.0)
+planner.add_time_window(2, start=0.0, end=6.0)
+
+# Set solver options
+planner.set_options(return_to_end=True, objective="min_max", time_limit=5)
+
+# Visualize the problem map
+planner.show_map()
+
+# Solve
+result = planner.solve()
+print(result["status"])
+for route in result["routes"]:
+    print(f"  Agent {route['agent_id']}: path={route['path']}, cost={route['cost']:.3f}")
+
+# Visualize the result
+planner.show_result(result)
+```
+
+### 4. Visualization
+
+#### `show_map` — view the problem before solving
+
+```python
+# Via Planner method:
+planner.show_map()
+
+# Or via module-level function:
+rch.show_map(planner)
+
+# Draw on an existing axes (e.g. for subplots):
+import matplotlib.pyplot as plt
+fig, ax = plt.subplots()
+rch.show_map(planner, ax=ax, show=False)
+plt.savefig("map.png")
+```
+
+Depots are drawn as black stars (★), targets as grey dots, and each agent's start position as a coloured triangle.
+
+#### `show_result` — view routes after solving
+
+```python
+result = planner.solve()
+
+# Via Planner method:
+planner.show_result(result)
+
+# Or via module-level function:
+rch.show_result(planner, result)
+```
+
+Each agent's route is drawn with a distinct colour and directional arrows.
+
+**`return_to_end=False` handling**: when the solver option `return_to_end` is `False`, the solver internally appends the depot as the last node in each route. `show_result` automatically detects this and removes the trailing depot from the visualization — the route will end at the last target visited, without drawing an edge back to the depot.
+
+### 5. Low-level programmatic API
+
+```python
+from rch import Problem, Solver, Options, ObjectiveType, NodeType
+from rch import Node, Agent, AssignmentConstraint, TimeWindowConstraint
+
+# Build a problem instance in code
+problem = Problem()
+
+# Add nodes
+for nid, (x, y), ntype in [(0, (0, 0), NodeType.DEPOT),
+                             (1, (1, 2), NodeType.TARGET),
+                             (2, (3, 1), NodeType.TARGET)]:
+    n = Node()
+    n.id = nid
+    n.position.x = x
+    n.position.y = y
+    n.type = ntype
+    problem.add_node(n)
+
+# Add agents
+a = Agent()
+a.id = 0
+a.type = "UAV"
+a.start_node = 0
+a.end_node = 0
+problem.add_agent(a, 0)
+
+a2 = Agent()
+a2.id = 1
+a2.type = "UAV"
+a2.start_node = 0
+a2.end_node = 0
+problem.add_agent(a2, 1)
+
+# Set cost matrix (one per agent type)
+import math
+nodes_xy = [(0,0), (1,2), (3,1)]
+n = len(nodes_xy)
+cost = [[0.0]*n for _ in range(n)]
+for i in range(n):
+    for j in range(n):
+        dx = nodes_xy[i][0] - nodes_xy[j][0]
+        dy = nodes_xy[i][1] - nodes_xy[j][1]
+        cost[i][j] = math.sqrt(dx*dx + dy*dy)
+problem.set_cost_matrix("UAV", cost)
+
+# Configure options
+problem.options().objective = ObjectiveType.MinMax
+problem.options().return_to_end = True
+problem.options().time_limit = 5.0
+
+# Solve
+opts = problem.options()
+solver = Solver(problem, opts)
+ret = solver.solve()
+result = solver.get_result()
+
+# Note: this low-level API follows the original C++ convention:
+# ret == 1 means success, ret == 0 means failure.
+print(f"Return code: {ret}")
+print(f"Paths: {result.paths}")
+print(f"Costs: {result.times}")
+```
+
+---
+
+## JSON Input Format
+
+```json
+{
+  "nodes": [
+    {"id": 0, "x": 0.0, "y": 0.0, "z": 0.0, "type": "depot"},
+    {"id": 1, "x": 1.5, "y": 2.3, "z": 0.0, "type": "target"}
+  ],
+  "agents": [
+    {
+      "id": 0,
+      "type": "TypeA",
+      "start_node": 0,
+      "end_node": 0,
+      "max_length": 100.0,
+      "capacity": 10.0
+    }
+  ],
+  "costs": {
+    "TypeA": [[0.0, 1.5], [1.5, 0.0]]
+  },
+  "constraints": [
+    {
+      "kind": "assignment",
+      "items": [
+        {"node": 1, "types": ["TypeA"]}
+      ]
+    },
+    {
+      "kind": "timewindow",
+      "items": [
+        {"node": 1, "start": 0.0, "end": 50.0}
+      ]
+    }
+  ],
+  "options": {
+    "return_to_end": true,
+    "objective": "min_max",
+    "time_limit": 60
+  }
+}
+```
+
+### Fields
+
+| Field | Description |
+|---|---|
+| `nodes` | List of nodes. Each has `id`, `x`, `y`, optional `z`, `type` (`"depot"` or `"target"`). |
+| `agents` | List of agents. Each has `id`, `type`, `start_node`, `end_node`, optional `max_length`, `capacity`. |
+| `costs` | Dict mapping agent type name → cost matrix (2D array, row = from node id, col = to node id). |
+| `constraints` | Optional. List of constraint blocks. `kind` = `"assignment"` or `"timewindow"`. |
+| `options` | Optional. `return_to_end` (bool), `objective` (`"min_max"` or `"min_sum"`), `time_limit` (seconds). |
+
+---
+
+## Result Format
+
+```python
+{
+    "status": "success",       # "success" or "failed"
+    "timeout": False,          # True if solver hit time limit
+    "routes": [
+        {
+            "agent_id": 0,
+            "path": [0, 2, 0],    # ordered node IDs
+            "cost": 6.32          # route cost
+        },
+        ...
+    ],
+    "statistics": {
+        "solve_time": 0.123,      # wall-clock time (s)
+        "max_cost": 6.32,         # maximum route cost
+        "sum_cost": 10.56,        # total cost of all routes
+        "n_generated": 1500,      # labels generated
+        "n_expanded": 800,        # labels expanded
+        "last_update_time": 0.08  # time of last solution improvement
+    },
+    "anytime": [
+        {"time": 0.01, "max_cost": 9.5, "sum_cost": 15.2},
+        {"time": 0.05, "max_cost": 7.1, "sum_cost": 12.0},
+        ...
+    ]
+}
+```
+
+---
+
+## API Reference
+
+### `rch.solve(source, *, time_limit=-1) → dict`
+
+Solve an MTSP instance.
+
+- `source` — file path (`str` / `Path`), raw JSON string, or Python `dict`.
+- `time_limit` — override the time limit in seconds (default: use the value in JSON).
+
+### `rch.Planner` (recommended)
+
+High-level builder API. All mutating methods return `self` for chaining.
+
+- `add_depot(node_id, *, x, y, z=0)` — add a depot node.
+- `add_target(node_id, *, x, y, z=0, demand=0)` — add a target node.
+- `add_agent(*, agent_id, agent_type, start_node, end_node, order=None, capacity_limit=-1, time_limit=-1)` — add an agent. `time_limit` is the max travel distance/time (≤0 means no limit).
+- `set_cost_matrix(agent_type, matrix)` — set cost matrix for an agent type.
+- `add_assignment(node_id, types)` — assign a node to a list of allowed agent types.
+- `add_time_window(node_id, start, end)` — add a time window constraint for a node.
+- `set_options(*, return_to_end=None, objective=None, time_limit=None)` — set solver options. `objective` accepts `"min_max"` or `"min_sum"`.
+- `solve() → dict` — run the solver and return a result dict.
+- `show_map(**kwargs) → Axes` — visualize the problem map (depots, targets, agent starts).
+- `show_result(result, **kwargs) → Axes` — visualize solved routes on the map.
+
+### `rch.show_map(planner, *, ax=None, figsize=(8,6), show=True) → Axes`
+
+Plot the problem map: depots (★), targets (●), and agent start positions (▲).
+
+### `rch.show_result(planner, result, *, ax=None, figsize=(8,6), show=True) → Axes`
+
+Plot solved routes on the map. Each agent's path is drawn with a distinct colour and directional arrows. When `return_to_end=False`, the trailing depot is automatically stripped from the visualization.
+
+### `rch.Problem`
+
+Low-level programmatic problem builder. Methods:
+
+- `add_node(node: Node)` — add a node.
+- `add_agent(agent: Agent, id: int)` — add an agent.
+- `set_cost_matrix(agent_type: str, matrix: List[List[float]])` — set cost matrix.
+- `set_assignment_constraint(c: AssignmentConstraint)` — set assignment constraint.
+- `set_timewindow_constraint(c: TimeWindowConstraint)` — set time window constraint.
+- `options() → Options` — access/modify solver options.
+
+### `rch.Solver`
+
+Low-level solver. Construct with `Solver(problem, options)`.
+
+- `solve() → int` — run the solver (1 = success, 0 = failure).
+- `get_result() → Result` — get the final result.
+- `get_result_process() → List[Tuple[float, Result]]` — get full anytime history.
+
+### `rch.ObjectiveType`
+
+Enum: `ObjectiveType.MinMax`, `ObjectiveType.MinSum`.
+
+### `rch.NodeType`
+
+Enum: `NodeType.DEPOT`, `NodeType.TARGET`.
+
+---
+
+## License
+
+MIT

pyrch-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+rch/__init__.py,sha256=xcLAs7JXtV9W-0CwPNRyjEP2C0ixAwzHqtX0YQd6ay8,1818
+rch/_api.py,sha256=Wlb_tiXxiAOgBWJ7J6SzsnMYcpt5ufz6Kf2-GogYVH8,9638
+rch/_rch_core.cp310-win_amd64.pyd,sha256=V8-m3wdwYEIvTF5mhxvkr5TEqQXcfnSah_RTewPAmq8,639488
+rch/_viz.py,sha256=Z04gacteFMGniVkXypgjHwN0ubvhCjToY5GmnBB_S1c,7820
+pyrch-0.1.0.dist-info/METADATA,sha256=37CEUgNkIcTyj6Gkc2jWr8eOXDOX3ZDkPpz53EZGcRo,12698
+pyrch-0.1.0.dist-info/WHEEL,sha256=rs4XyvYyY8p6GzRLerHjRm6wNH1QAkDMf7SSChBeqNk,106
+pyrch-0.1.0.dist-info/RECORD,,

pyrch-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: scikit-build-core 0.12.2
+Root-Is-Purelib: false
+Tag: cp310-cp310-win_amd64
+

rch/__init__.py

@@ -0,0 +1,77 @@
+"""
+RCH Solver — Partial-Expansion Anytime Focal Search for Heterogeneous Multi-Agent TSP.
+
+Quick start
+-----------
+>>> import rch
+>>> result = rch.solve("problem.json", time_limit=10)
+>>> print(result["status"])        # "success" or "failed"
+>>> print(result["statistics"])    # {"max_cost": ..., "sum_cost": ..., ...}
+
+Programmatic API
+----------------
+>>> from rch import Problem, Solver, ObjectiveType, NodeType
+>>> problem = Problem()
+>>> problem.add_target(0, x=1.0, y=2.0)
+>>> ...
+>>> result = problem.solve(time_limit=10)
+"""
+
+from rch._api import (
+    solve,
+    Planner,
+    Problem,
+    Solver,
+    ObjectiveType,
+    NodeType,
+    Position,
+    Node,
+    Agent,
+    Options,
+    Result,
+    AssignmentConstraint,
+    TimeWindowConstraint,
+)
+
+__version__ = "0.1.0"
+
+
+def show_map(*args, **kwargs):
+    try:
+        from rch._viz import show_map as _show_map
+    except ModuleNotFoundError as exc:
+        raise ImportError(
+            "Visualization support requires matplotlib. "
+            'Install it with: pip install "PyRCH[viz]"'
+        ) from exc
+    return _show_map(*args, **kwargs)
+
+
+def show_result(*args, **kwargs):
+    try:
+        from rch._viz import show_result as _show_result
+    except ModuleNotFoundError as exc:
+        raise ImportError(
+            "Visualization support requires matplotlib. "
+            'Install it with: pip install "PyRCH[viz]"'
+        ) from exc
+    return _show_result(*args, **kwargs)
+
+__all__ = [
+    "solve",
+    "Planner",
+    "Problem",
+    "Solver",
+    "ObjectiveType",
+    "NodeType",
+    "Position",
+    "Node",
+    "Agent",
+    "Options",
+    "Result",
+    "AssignmentConstraint",
+    "TimeWindowConstraint",
+    "show_map",
+    "show_result",
+    "__version__",
+]

rch/_api.py

@@ -0,0 +1,286 @@
+"""
+High-level Pythonic API for the RCH MTSP Solver.
+
+This module wraps the C++ ``_rch_core`` extension and exposes a
+convenient interface for solving heterogeneous multi-agent TSP instances.
+"""
+
+from __future__ import annotations
+
+import json as _json
+import pathlib
+import time as _time
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Union
+
+# Re-export low-level C++ types so users can do  ``from rch import Problem``
+from rch._rch_core import (          # type: ignore[import-not-found]
+    ObjectiveType,
+    NodeType,
+    Position,
+    Node,
+    Agent,
+    Options,
+    AssignmentConstraint,
+    TimeWindowConstraint,
+    Problem,
+    Result,
+    Solver,
+    solve_json_file as _solve_json_file,
+    solve_json_str  as _solve_json_str,
+)
+
+
+# --------------------------------------------------------------------- #
+#  Convenience wrapper                                                   #
+# --------------------------------------------------------------------- #
+
+def _normalize_problem_data(data: Dict[str, Any]) -> Dict[str, Any]:
+    """Fill in Python-side defaults expected by the C++ JSON loader."""
+    normalized = _json.loads(_json.dumps(data))
+    for node in normalized.get("nodes", []):
+        node.setdefault("z", 0.0)
+    return normalized
+
+
+def _solve_from_json_data(data: Dict[str, Any], time_limit: float) -> Dict[str, Any]:
+    normalized = _normalize_problem_data(data)
+    return _solve_json_str(_json.dumps(normalized), time_limit)
+
+
+def _looks_like_json_text(source: str) -> bool:
+    stripped = source.lstrip()
+    return bool(stripped) and stripped[0] in "[{"
+
+
+def solve(
+    source: Union[str, pathlib.Path, dict],
+    *,
+    time_limit: float = -1,
+) -> Dict[str, Any]:
+    """Solve an MTSP instance and return the result as a plain dict.
+
+    Parameters
+    ----------
+    source : str | pathlib.Path | dict
+        - If a *str* or *Path* that points to an existing file, it is
+          treated as a JSON file path.
+        - If a *str* that does **not** point to an existing file, it is
+          treated as a raw JSON string.
+        - If a *dict*, it is serialized to JSON and solved.
+    time_limit : float, optional
+        Override the time limit in the JSON options (seconds).  A value
+        <= 0 means "use whatever the JSON says".
+
+    Returns
+    -------
+    dict
+        ``{"status": "success"|"failed",
+           "timeout": bool,
+           "routes": [...],
+           "statistics": {...},
+           "anytime": [...]}``
+    """
+    if isinstance(source, dict):
+        return _solve_from_json_data(source, time_limit)
+
+    if isinstance(source, pathlib.Path):
+        return _solve_from_json_data(_json.loads(source.read_text()), time_limit)
+
+    text = str(source)
+    if _looks_like_json_text(text):
+        return _solve_from_json_data(_json.loads(text), time_limit)
+
+    try:
+        path = pathlib.Path(text)
+        if path.is_file():
+            return _solve_from_json_data(_json.loads(path.read_text()), time_limit)
+    except OSError:
+        pass
+
+    # Fall back to treating the input as raw JSON text.
+    return _solve_from_json_data(_json.loads(text), time_limit)
+
+
+def _result_to_dict(result: Result, problem: Problem, solve_time: float) -> Dict[str, Any]:
+    routes: List[Dict[str, Any]] = []
+    max_cost = 0.0
+    sum_cost = 0.0
+
+    for agent in problem.agents_ordered():
+        path = list(result.paths.get(agent.id, []))
+        cost = float(result.times.get(agent.id, 0.0))
+        routes.append({"agent_id": agent.id, "path": path, "cost": cost})
+        max_cost = max(max_cost, cost)
+        sum_cost += cost
+
+    return {
+        "status": "success" if result.paths else "failed",
+        "timeout": result.timeout,
+        "routes": routes,
+        "statistics": {
+            "solve_time": solve_time,
+            "max_cost": max_cost,
+            "sum_cost": sum_cost,
+            "n_generated": result.n_generated,
+            "n_expanded": result.n_expanded,
+            "last_update_time": result.last_update_time,
+        },
+    }
+
+
+def _anytime_to_list(
+    history: Sequence[Tuple[float, Result]], *, min_sum: bool
+) -> List[Dict[str, float]]:
+    out: List[Dict[str, float]] = []
+    best = float("inf")
+    for t, res in history:
+        max_cost = 0.0
+        sum_cost = 0.0
+        for cost in res.times.values():
+            max_cost = max(max_cost, float(cost))
+            sum_cost += float(cost)
+        obj = sum_cost if min_sum else max_cost
+        if obj < best - 1e-9:
+            best = obj
+            out.append({"time": float(t), "max_cost": max_cost, "sum_cost": sum_cost})
+    return out
+
+
+class Planner:
+    """Object-style builder API for constructing and solving MTSP problems."""
+
+    def __init__(self) -> None:
+        self.problem = Problem()
+        self._assignment = AssignmentConstraint()
+        self._timewindow = TimeWindowConstraint()
+
+    def add_depot(self, node_id: int, *, x: float, y: float, z: float = 0.0) -> "Planner":
+        node = Node()
+        node.id = node_id
+        node.position.x = x
+        node.position.y = y
+        node.position.z = z
+        node.type = NodeType.DEPOT
+        self.problem.add_node(node)
+        return self
+
+    def add_target(
+        self,
+        node_id: int,
+        *,
+        x: float,
+        y: float,
+        z: float = 0.0,
+        demand: float = 0.0,
+    ) -> "Planner":
+        node = Node()
+        node.id = node_id
+        node.position.x = x
+        node.position.y = y
+        node.position.z = z
+        node.type = NodeType.TARGET
+        node.demand = demand
+        self.problem.add_node(node)
+        return self
+
+    def add_agent(
+        self,
+        *,
+        agent_id: int,
+        agent_type: str,
+        start_node: int,
+        end_node: int,
+        order: Optional[int] = None,
+        capacity_limit: float = -1.0,
+        time_limit: float = -1.0,
+    ) -> "Planner":
+        agent = Agent()
+        agent.id = agent_id
+        agent.type = agent_type
+        agent.start_node = start_node
+        agent.end_node = end_node
+        agent.capacity_limit = capacity_limit
+        agent.time_limit = time_limit
+        self.problem.add_agent(agent, agent_id if order is None else order)
+        return self
+
+    def set_cost_matrix(
+        self, agent_type: str, matrix: Sequence[Sequence[float]]
+    ) -> "Planner":
+        self.problem.set_cost_matrix(agent_type, matrix)
+        return self
+
+    def add_assignment(self, node_id: int, types: Iterable[str]) -> "Planner":
+        self._assignment.set_assignment(node_id, list(types))
+        self.problem.set_assignment_constraint(self._assignment)
+        return self
+
+    def add_timewindow(self, node_id: int, start: float, end: float) -> "Planner":
+        self._timewindow.set_timewindow(node_id, start, end)
+        self.problem.set_timewindow_constraint(self._timewindow)
+        return self
+
+    def add_time_window(self, node_id: int, start: float, end: float) -> "Planner":
+        """Alias of add_timewindow()."""
+        return self.add_timewindow(node_id, start, end)
+
+    def set_options(
+        self,
+        *,
+        return_to_end: Optional[bool] = None,
+        objective: Optional[Union[str, ObjectiveType]] = None,
+        time_limit: Optional[float] = None,
+    ) -> "Planner":
+        opts = self.problem.options()
+        if return_to_end is not None:
+            opts.return_to_end = return_to_end
+        if objective is not None:
+            if isinstance(objective, str):
+                key = objective.strip().lower()
+                if key in ("min_max", "minmax"):
+                    opts.objective = ObjectiveType.MinMax
+                elif key in ("min_sum", "minsum"):
+                    opts.objective = ObjectiveType.MinSum
+                else:
+                    raise ValueError("objective must be one of: min_max, min_sum")
+            else:
+                opts.objective = objective
+        if time_limit is not None:
+            opts.time_limit = time_limit
+        return self
+
+    def solve(self) -> Dict[str, Any]:
+        options = self.problem.options()
+        t0 = _time.perf_counter()
+        solver = Solver(self.problem, options)
+        solver.solve()
+        solve_time = _time.perf_counter() - t0
+
+        result = solver.get_result()
+        out = _result_to_dict(result, self.problem, solve_time)
+        out["anytime"] = _anytime_to_list(
+            solver.get_result_process(),
+            min_sum=(options.objective == ObjectiveType.MinSum),
+        )
+        return out
+
+    # ── Visualization convenience methods ────────────────────────────
+
+    def show_map(self, **kwargs):
+        """Plot depots, targets and agent start positions.
+
+        Keyword arguments are forwarded to :func:`rch.show_map`.
+        """
+        from rch._viz import show_map as _show_map
+        return _show_map(self, **kwargs)
+
+    def show_result(self, result: Dict[str, Any], **kwargs):
+        """Plot solved routes on the map.
+
+        If ``return_to_end=False``, the trailing depot node appended by
+        the solver is automatically removed from the visualization.
+
+        Keyword arguments are forwarded to :func:`rch.show_result`.
+        """
+        from rch._viz import show_result as _show_result
+        return _show_result(self, result, **kwargs)

rch/_viz.py

@@ -0,0 +1,243 @@
+"""
+Visualization helpers for the RCH MTSP Solver.
+
+Provides:
+  - show_map(planner)    : plot depots and targets with agent start positions.
+  - show_result(planner, result) : plot solved routes on the map.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from rch._api import Planner
+
+import matplotlib.pyplot as plt
+
+
+# ── Colour palette (tab10-derived, easy to distinguish) ──────────────
+_AGENT_COLORS = [
+    "#1f77b4", "#ff7f0e", "#2ca02c", "#d62728",
+    "#9467bd", "#8c564b", "#e377c2", "#7f7f7f",
+    "#bcbd22", "#17becf",
+]
+
+def _color_for(idx: int) -> str:
+    return _AGENT_COLORS[idx % len(_AGENT_COLORS)]
+
+
+# ── Internal: collect node info from a Planner ───────────────────────
+def _collect_nodes(planner: "Planner"):
+    """Return (depots, targets) as lists of (id, x, y)."""
+    from rch._rch_core import NodeType  # type: ignore[import-not-found]
+
+    depots, targets = [], []
+    for node in planner.problem.nodes():
+        pos = node.position
+        entry = (node.id, pos.x, pos.y)
+        if node.type == NodeType.DEPOT:
+            depots.append(entry)
+        else:
+            targets.append(entry)
+    return depots, targets
+
+
+def _collect_agents(planner: "Planner"):
+    """Return list of (id, type, start_node, end_node)."""
+    agents = []
+    for a in planner.problem.agents_ordered():
+        agents.append((a.id, a.type, a.start_node, a.end_node))
+    return agents
+
+
+def _node_pos_map(planner: "Planner") -> Dict[int, tuple]:
+    """node_id → (x, y)"""
+    return {
+        n.id: (n.position.x, n.position.y)
+        for n in planner.problem.nodes()
+    }
+
+
+# ── Public API ───────────────────────────────────────────────────────
+
+def show_map(
+    planner: "Planner",
+    *,
+    ax: Optional[plt.Axes] = None,
+    figsize: tuple = (8, 6),
+    show: bool = True,
+) -> plt.Axes:
+    """Plot the problem map: depots (★), targets (●), and agent start positions.
+
+    Parameters
+    ----------
+    planner : rch.Planner
+        A planner instance with nodes and agents already added.
+    ax : matplotlib Axes, optional
+        If provided, draw on this axes; otherwise create a new figure.
+    figsize : tuple
+        Figure size when creating a new figure.
+    show : bool
+        If True, call ``plt.show()`` at the end (set False to compose plots).
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    depots, targets = _collect_nodes(planner)
+    agents = _collect_agents(planner)
+    pos_map = _node_pos_map(planner)
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=figsize)
+
+    # Draw targets
+    if targets:
+        tx = [t[1] for t in targets]
+        ty = [t[2] for t in targets]
+        ax.scatter(tx, ty, c="grey", s=60, zorder=3, label="Target")
+        for nid, x, y in targets:
+            ax.annotate(str(nid), (x, y), textcoords="offset points",
+                        xytext=(5, 5), fontsize=8, color="grey")
+
+    # Draw depots
+    if depots:
+        dx = [d[1] for d in depots]
+        dy = [d[2] for d in depots]
+        ax.scatter(dx, dy, c="black", marker="*", s=200, zorder=4, label="Depot")
+        for nid, x, y in depots:
+            ax.annotate(str(nid), (x, y), textcoords="offset points",
+                        xytext=(5, 5), fontsize=9, fontweight="bold")
+
+    # Draw agent start positions (small markers next to depot)
+    for idx, (aid, atype, start, end) in enumerate(agents):
+        if start in pos_map:
+            sx, sy = pos_map[start]
+            color = _color_for(idx)
+            ax.scatter([sx], [sy], marker="^", c=color, s=100, zorder=5,
+                       edgecolors="black", linewidths=0.6,
+                       label=f"Agent {aid} ({atype})")
+
+    ax.set_xlabel("X")
+    ax.set_ylabel("Y")
+    ax.legend(fontsize=9, loc="best")
+    ax.set_aspect("equal", adjustable="datalim")
+    ax.grid(True, alpha=0.3)
+
+    if show:
+        plt.tight_layout()
+        plt.show()
+    return ax
+
+
+def show_result(
+    planner: "Planner",
+    result: Dict[str, Any],
+    *,
+    ax: Optional[plt.Axes] = None,
+    figsize: tuple = (8, 6),
+    show: bool = True,
+) -> plt.Axes:
+    """Plot solved routes on the problem map.
+
+    Each agent's path is drawn with a distinct colour and optional arrows.
+    If ``return_to_end`` is ``False``, the final node in each route
+    (which is the depot added by the solver) is stripped, and no edge
+    is drawn back to that depot.
+
+    Parameters
+    ----------
+    planner : rch.Planner
+        The planner used to solve the problem.
+    result : dict
+        The result dict returned by ``planner.solve()``.
+    ax : matplotlib Axes, optional
+    figsize : tuple
+    show : bool
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    depots, targets = _collect_nodes(planner)
+    agents = _collect_agents(planner)
+    pos_map = _node_pos_map(planner)
+
+    # Detect return_to_end setting
+    return_to_end = planner.problem.options().return_to_end
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=figsize)
+
+    # Draw targets
+    if targets:
+        tx = [t[1] for t in targets]
+        ty = [t[2] for t in targets]
+        ax.scatter(tx, ty, c="grey", s=60, zorder=3, label="Target")
+        for nid, x, y in targets:
+            ax.annotate(str(nid), (x, y), textcoords="offset points",
+                        xytext=(5, 5), fontsize=8, color="grey")
+
+    # Draw depots
+    if depots:
+        dx = [d[1] for d in depots]
+        dy = [d[2] for d in depots]
+        ax.scatter(dx, dy, c="black", marker="*", s=200, zorder=4, label="Depot")
+        for nid, x, y in depots:
+            ax.annotate(str(nid), (x, y), textcoords="offset points",
+                        xytext=(5, 5), fontsize=9, fontweight="bold")
+
+    # Build depot-id set for trimming
+    depot_ids = {d[0] for d in depots}
+
+    # Draw each agent's route
+    routes = result.get("routes", [])
+    for idx, route in enumerate(routes):
+        aid = route["agent_id"]
+        path = list(route["path"])
+        cost = route.get("cost", 0.0)
+
+        if not path:
+            continue
+
+        # If return_to_end=False, the solver still appends the depot as
+        # the last node; remove it so the visualization doesn't draw
+        # the return edge.
+        if not return_to_end and len(path) > 1 and path[-1] in depot_ids:
+            path = path[:-1]
+
+        color = _color_for(idx)
+
+        # Collect (x, y) coordinates along the path
+        xs = [pos_map[nid][0] for nid in path if nid in pos_map]
+        ys = [pos_map[nid][1] for nid in path if nid in pos_map]
+
+        if len(xs) < 2:
+            continue
+
+        # Draw path with arrows
+        ax.plot(xs, ys, color=color, linewidth=2, alpha=0.8, zorder=2,
+                label=f"Agent {aid} (cost={cost:.2f})")
+
+        # Draw arrows along each segment
+        for i in range(len(xs) - 1):
+            dx = xs[i + 1] - xs[i]
+            dy = ys[i + 1] - ys[i]
+            ax.annotate(
+                "", xy=(xs[i + 1], ys[i + 1]),
+                xytext=(xs[i], ys[i]),
+                arrowprops=dict(arrowstyle="->", color=color, lw=1.5),
+                zorder=2,
+            )
+
+    ax.set_xlabel("X")
+    ax.set_ylabel("Y")
+    ax.legend(fontsize=9, loc="best")
+    ax.set_aspect("equal", adjustable="datalim")
+    ax.grid(True, alpha=0.3)
+
+    if show:
+        plt.tight_layout()
+        plt.show()
+    return ax