solverpilot 0.1__py3-none-any.whl

solverpilot/applications/tsp/distance.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import isclose
+from typing import Sequence
+
+from .errors import TSPValidationError
+from .model import TSPDistanceMatrix, TSPInstance
+
+
+@dataclass(frozen=True, slots=True)
+class TSPDistanceAnalysis:
+    symmetric: bool
+    zero_diagonal: bool
+    triangle_inequality: bool | None
+    metric: bool | None
+    atol: float
+
+
+def analyze_distance_matrix(
+    matrix: TSPDistanceMatrix | Sequence[Sequence[float]],
+    *,
+    atol: float = 1e-12,
+    check_triangle: bool = True,
+) -> TSPDistanceAnalysis:
+    if not isinstance(atol, (int, float)) or isinstance(atol, bool) or float(atol) < 0.0:
+        raise TSPValidationError("atol must be a non-negative finite number")
+    atol = float(atol)
+    if atol == float("inf") or atol != atol:
+        raise TSPValidationError("atol must be finite")
+    dm = matrix if isinstance(matrix, TSPDistanceMatrix) else TSPDistanceMatrix(matrix)
+    n = dm.n_nodes
+    symmetric = all(isclose(dm.values[i][j], dm.values[j][i], rel_tol=0.0, abs_tol=atol) for i in range(n) for j in range(i + 1, n))
+    zero_diagonal = all(abs(dm.values[i][i]) <= atol for i in range(n))
+    triangle: bool | None = None
+    metric: bool | None = None
+    if check_triangle:
+        triangle = True
+        for i in range(n):
+            for j in range(n):
+                dij = dm.values[i][j]
+                for k in range(n):
+                    if dij > dm.values[i][k] + dm.values[k][j] + atol:
+                        triangle = False
+                        break
+                if not triangle:
+                    break
+            if not triangle:
+                break
+        metric = symmetric and zero_diagonal and triangle
+    return TSPDistanceAnalysis(symmetric, zero_diagonal, triangle, metric, atol)
+
+
+def route_cost(instance: TSPInstance, route: Sequence[int]) -> float:
+    if len(route) < 2:
+        raise TSPValidationError("route must contain at least two entries")
+    total = 0.0
+    for a, b in zip(route, route[1:]):
+        total += instance.distances.edge_cost(a, b)
+    return float(total)

solverpilot/applications/tsp/errors.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+
+class TSPError(ValueError):
+    """Base error for the SolverPilot TSP application pack."""
+
+
+class TSPValidationError(TSPError):
+    """Raised when a TSP model, route, or solution is invalid."""
+
+
+class TSPCompileError(TSPError):
+    """Raised when an exact compiler cannot preserve TSP semantics safely."""
+
+
+class TSPReferenceLimitError(TSPError):
+    """Raised when an exponential exact reference solver hits its safety guard."""

solverpilot/applications/tsp/heuristics.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from time import perf_counter
+from typing import Sequence
+
+from .distance import analyze_distance_matrix, route_cost
+from .errors import TSPValidationError
+from .model import TSPInstance
+from .solution import TSPSolution
+from .validation import validate_tsp_route
+
+
+def _start(instance: TSPInstance, value: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or not 0 <= value < instance.n_nodes:
+        raise TSPValidationError("start_index must be an in-range integer")
+    return value
+
+
+def solve_tsp_nearest_neighbor(instance: TSPInstance, *, start_index: int = 0) -> TSPSolution:
+    start = _start(instance, start_index)
+    t0 = perf_counter()
+    unvisited = set(range(instance.n_nodes))
+    unvisited.remove(start)
+    route = [start]
+    current = start
+    while unvisited:
+        nxt = min(unvisited, key=lambda j: (instance.distances.values[current][j], j))
+        route.append(nxt)
+        unvisited.remove(nxt)
+        current = nxt
+    route.append(start)
+    objective = route_cost(instance, route)
+    return TSPSolution(route, objective, method="nearest-neighbor", is_exact=False, optimality_proven=False, runtime_seconds=perf_counter()-t0, metadata={"start_index": start})
+
+
+def solve_tsp_multistart_nearest_neighbor(instance: TSPInstance, *, start_indices: Sequence[int] | None = None) -> TSPSolution:
+    if start_indices is None:
+        starts = tuple(range(instance.n_nodes))
+    else:
+        if isinstance(start_indices, (str, bytes)):
+            raise TSPValidationError("start_indices must be a sequence of integers")
+        starts = tuple(dict.fromkeys(_start(instance, x) for x in start_indices))
+        if not starts:
+            raise TSPValidationError("start_indices must not be empty")
+    t0 = perf_counter()
+    candidates = [solve_tsp_nearest_neighbor(instance, start_index=s) for s in starts]
+    best = min(candidates, key=lambda x: (x.objective, x.route))
+    return TSPSolution(best.route, best.objective, method="multistart-nearest-neighbor", is_exact=False, optimality_proven=False, runtime_seconds=perf_counter()-t0, metadata={"start_indices": starts, "candidate_objectives": tuple(x.objective for x in candidates)})
+
+
+def solve_tsp_two_opt(
+    instance: TSPInstance,
+    *,
+    initial_route: Sequence[int] | TSPSolution | None = None,
+    start_index: int = 0,
+    max_iterations: int = 1000,
+    strategy: str = "best",
+    symmetry_atol: float = 1e-12,
+) -> TSPSolution:
+    if isinstance(max_iterations, bool) or not isinstance(max_iterations, int) or max_iterations < 1:
+        raise TSPValidationError("max_iterations must be a positive integer")
+    strategy = str(strategy).strip().lower()
+    if strategy not in {"best", "first"}:
+        raise TSPValidationError("strategy must be 'best' or 'first'")
+    start = _start(instance, start_index)
+    if initial_route is None:
+        route = (start, *(i for i in range(instance.n_nodes) if i != start), start)
+    elif isinstance(initial_route, TSPSolution):
+        route = tuple(initial_route.route)
+    else:
+        route = tuple(initial_route)
+    report = validate_tsp_route(instance, route)
+    if not report.valid:
+        raise TSPValidationError("initial_route is invalid: " + "; ".join(report.errors))
+    if route[0] != start:
+        raise TSPValidationError("initial_route must start at start_index")
+    t0 = perf_counter()
+    symmetric = analyze_distance_matrix(instance.distances, atol=symmetry_atol, check_triangle=False).symmetric
+    current = route
+    current_cost = route_cost(instance, current)
+    initial_cost = current_cost
+    moves_evaluated = 0
+    improvements = 0
+    iterations = 0
+    n = instance.n_nodes
+    for iteration in range(max_iterations):
+        iterations = iteration + 1
+        best_route: tuple[int, ...] | None = None
+        best_cost = current_cost
+        for i in range(1, n - 1):
+            for k in range(i + 1, n):
+                moves_evaluated += 1
+                candidate = current[:i] + tuple(reversed(current[i:k+1])) + current[k+1:]
+                if symmetric:
+                    a, b, c, d = current[i-1], current[i], current[k], current[k+1]
+                    candidate_cost = current_cost - instance.distances.values[a][b] - instance.distances.values[c][d] + instance.distances.values[a][c] + instance.distances.values[b][d]
+                else:
+                    # Reversal changes all internal arc directions for an asymmetric TSP.
+                    candidate_cost = route_cost(instance, candidate)
+                if candidate_cost + 1e-12 < best_cost:
+                    best_route, best_cost = candidate, float(candidate_cost)
+                    if strategy == "first":
+                        break
+            if strategy == "first" and best_route is not None:
+                break
+        if best_route is None:
+            break
+        current = best_route
+        current_cost = route_cost(instance, current)  # keep accumulated deltas from becoming the authority
+        improvements += 1
+    final_cost = route_cost(instance, current)
+    return TSPSolution(current, final_cost, method="two-opt", is_exact=False, optimality_proven=False, runtime_seconds=perf_counter()-t0, metadata={"start_index": start, "symmetric_fast_delta": symmetric, "initial_cost": initial_cost, "improvements": improvements, "moves_evaluated": moves_evaluated, "iterations": iterations, "strategy": strategy})

solverpilot/applications/tsp/model.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from math import hypot, isfinite
+from types import MappingProxyType
+from typing import Any, Mapping, Sequence
+
+from .errors import TSPValidationError
+
+
+def _frozen_metadata(value: Mapping[str, Any] | None) -> Mapping[str, Any]:
+    return MappingProxyType(dict(value or {}))
+
+
+@dataclass(frozen=True, slots=True)
+class TSPNode:
+    id: str
+    x: float | None = None
+    y: float | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict, compare=False)
+
+    def __post_init__(self) -> None:
+        node_id = str(self.id).strip()
+        if not node_id:
+            raise TSPValidationError("TSP node id must be a non-empty string")
+        object.__setattr__(self, "id", node_id)
+        if (self.x is None) != (self.y is None):
+            raise TSPValidationError("TSP coordinates must provide both x and y or neither")
+        if self.x is not None:
+            if isinstance(self.x, bool) or isinstance(self.y, bool):
+                raise TSPValidationError("TSP node coordinates must be numeric, not bool")
+            try:
+                x = float(self.x)
+                y = float(self.y)
+            except (TypeError, ValueError) as exc:
+                raise TSPValidationError("TSP node coordinates must be numeric") from exc
+            if not isfinite(x) or not isfinite(y):
+                raise TSPValidationError("TSP node coordinates must be finite")
+            object.__setattr__(self, "x", x)
+            object.__setattr__(self, "y", y)
+        object.__setattr__(self, "metadata", _frozen_metadata(self.metadata))
+
+
+@dataclass(frozen=True, slots=True)
+class TSPDistanceMatrix:
+    values: tuple[tuple[float, ...], ...]
+
+    def __init__(self, values: Sequence[Sequence[float]]):
+        try:
+            raw_rows = tuple(tuple(row) for row in values)
+        except TypeError as exc:
+            raise TSPValidationError("TSP distance matrix must be a sequence of rows") from exc
+        rows_list: list[tuple[float, ...]] = []
+        for i, row in enumerate(raw_rows):
+            normalized: list[float] = []
+            for j, value in enumerate(row):
+                if isinstance(value, bool):
+                    raise TSPValidationError(f"distance at ({i}, {j}) must be numeric, not bool")
+                try:
+                    normalized.append(float(value))
+                except (TypeError, ValueError) as exc:
+                    raise TSPValidationError(f"distance at ({i}, {j}) must be numeric") from exc
+            rows_list.append(tuple(normalized))
+        rows = tuple(rows_list)
+        if len(rows) < 2:
+            raise TSPValidationError("a TSP distance matrix must contain at least two nodes")
+        n = len(rows)
+        if any(len(row) != n for row in rows):
+            raise TSPValidationError("TSP distance matrix must be square")
+        for i, row in enumerate(rows):
+            for j, value in enumerate(row):
+                if not isfinite(value):
+                    raise TSPValidationError(f"distance at ({i}, {j}) must be finite")
+                if value < 0.0:
+                    raise TSPValidationError(f"distance at ({i}, {j}) must be non-negative")
+        object.__setattr__(self, "values", rows)
+
+    @property
+    def n_nodes(self) -> int:
+        return len(self.values)
+
+    def edge_cost(self, start: int, end: int) -> float:
+        if isinstance(start, bool) or isinstance(end, bool):
+            raise TSPValidationError("node indices must be integers, not bool")
+        if not isinstance(start, int) or not isinstance(end, int):
+            raise TSPValidationError("node indices must be integers")
+        if not (0 <= start < self.n_nodes and 0 <= end < self.n_nodes):
+            raise TSPValidationError("node index outside TSP distance matrix")
+        return self.values[start][end]
+
+
+@dataclass(frozen=True, slots=True)
+class TSPInstance:
+    nodes: tuple[TSPNode, ...]
+    distances: TSPDistanceMatrix
+    name: str = "tsp"
+    metadata: Mapping[str, Any] = field(default_factory=dict, compare=False)
+
+    def __init__(
+        self,
+        nodes: Sequence[TSPNode],
+        distances: TSPDistanceMatrix | Sequence[Sequence[float]],
+        *,
+        name: str = "tsp",
+        metadata: Mapping[str, Any] | None = None,
+    ) -> None:
+        node_tuple = tuple(nodes)
+        matrix = distances if isinstance(distances, TSPDistanceMatrix) else TSPDistanceMatrix(distances)
+        if len(node_tuple) != matrix.n_nodes:
+            raise TSPValidationError("node count must match the distance matrix size")
+        ids = tuple(node.id for node in node_tuple)
+        if len(set(ids)) != len(ids):
+            raise TSPValidationError("TSP node ids must be unique")
+        clean_name = str(name).strip()
+        if not clean_name:
+            raise TSPValidationError("TSP instance name must be non-empty")
+        object.__setattr__(self, "nodes", node_tuple)
+        object.__setattr__(self, "distances", matrix)
+        object.__setattr__(self, "name", clean_name)
+        object.__setattr__(self, "metadata", _frozen_metadata(metadata))
+
+    @property
+    def n_nodes(self) -> int:
+        return len(self.nodes)
+
+    @property
+    def node_ids(self) -> tuple[str, ...]:
+        return tuple(node.id for node in self.nodes)
+
+    @classmethod
+    def from_distance_matrix(
+        cls,
+        matrix: Sequence[Sequence[float]],
+        *,
+        node_ids: Sequence[str] | None = None,
+        name: str = "tsp",
+        metadata: Mapping[str, Any] | None = None,
+    ) -> "TSPInstance":
+        distances = TSPDistanceMatrix(matrix)
+        ids = tuple(str(i) for i in range(distances.n_nodes)) if node_ids is None else tuple(node_ids)
+        if len(ids) != distances.n_nodes:
+            raise TSPValidationError("node_ids length must match the distance matrix")
+        return cls(tuple(TSPNode(node_id) for node_id in ids), distances, name=name, metadata=metadata)
+
+    @classmethod
+    def from_coordinates(
+        cls,
+        coordinates: Sequence[tuple[float, float]],
+        *,
+        node_ids: Sequence[str] | None = None,
+        round_digits: int | None = None,
+        name: str = "tsp",
+        metadata: Mapping[str, Any] | None = None,
+    ) -> "TSPInstance":
+        if len(coordinates) < 2:
+            raise TSPValidationError("a TSP instance requires at least two coordinates")
+        if round_digits is not None:
+            if isinstance(round_digits, bool) or not isinstance(round_digits, int) or round_digits < 0:
+                raise TSPValidationError("round_digits must be a non-negative integer or None")
+        ids = tuple(str(i) for i in range(len(coordinates))) if node_ids is None else tuple(node_ids)
+        if len(ids) != len(coordinates):
+            raise TSPValidationError("node_ids length must match coordinates")
+        nodes = tuple(TSPNode(node_id, x, y) for node_id, (x, y) in zip(ids, coordinates))
+        rows: list[tuple[float, ...]] = []
+        for a in nodes:
+            if a.x is None or a.y is None:
+                raise TSPValidationError("coordinate-backed TSP node unexpectedly lacks coordinates")
+            row: list[float] = []
+            for b in nodes:
+                if b.x is None or b.y is None:
+                    raise TSPValidationError("coordinate-backed TSP node unexpectedly lacks coordinates")
+                value = hypot(a.x - b.x, a.y - b.y)
+                row.append(round(value, round_digits) if round_digits is not None else value)
+            rows.append(tuple(row))
+        return cls(nodes, rows, name=name, metadata=metadata)

solverpilot/applications/tsp/reference.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from itertools import permutations
+from math import inf
+from time import perf_counter
+
+from .distance import route_cost
+from .errors import TSPReferenceLimitError, TSPValidationError
+from .model import TSPInstance
+from .solution import TSPSolution, _INDEPENDENT_PROOF_TOKEN
+
+
+def _validate_start(instance: TSPInstance, start_index: int) -> int:
+    if isinstance(start_index, bool) or not isinstance(start_index, int):
+        raise TSPValidationError("start_index must be an integer")
+    if not 0 <= start_index < instance.n_nodes:
+        raise TSPValidationError("start_index is outside the TSP instance")
+    return start_index
+
+
+def _validate_limit(max_nodes: int, *, minimum: int = 2) -> int:
+    if isinstance(max_nodes, bool) or not isinstance(max_nodes, int) or max_nodes < minimum:
+        raise TSPValidationError(f"max_nodes must be an integer >= {minimum}")
+    return max_nodes
+
+
+def solve_tsp_brute_force(instance: TSPInstance, *, start_index: int = 0, max_nodes: int = 10) -> TSPSolution:
+    start = _validate_start(instance, start_index)
+    limit = _validate_limit(max_nodes)
+    if instance.n_nodes > limit:
+        raise TSPReferenceLimitError(f"brute force refused {instance.n_nodes} nodes because max_nodes={limit}")
+    t0 = perf_counter()
+    rest = tuple(i for i in range(instance.n_nodes) if i != start)
+    best_route: tuple[int, ...] | None = None
+    best_cost = inf
+    examined = 0
+    for ordering in permutations(rest):
+        route = (start, *ordering, start)
+        cost = route_cost(instance, route)
+        examined += 1
+        if cost < best_cost or (cost == best_cost and (best_route is None or route < best_route)):
+            best_route, best_cost = route, cost
+    if best_route is None:
+        raise RuntimeError("TSP brute-force search produced no route")
+    return TSPSolution(
+        best_route,
+        best_cost,
+        method="brute-force",
+        is_exact=True,
+        optimality_proven=True,
+        _proof_token=_INDEPENDENT_PROOF_TOKEN,
+        runtime_seconds=perf_counter() - t0,
+        metadata={"start_index": start, "permutations_evaluated": examined, "max_nodes": limit},
+    )
+
+
+def solve_tsp_held_karp(instance: TSPInstance, *, start_index: int = 0, max_nodes: int = 18) -> TSPSolution:
+    start = _validate_start(instance, start_index)
+    limit = _validate_limit(max_nodes)
+    if instance.n_nodes > limit:
+        raise TSPReferenceLimitError(f"Held-Karp refused {instance.n_nodes} nodes because max_nodes={limit}")
+    t0 = perf_counter()
+    nodes = tuple(i for i in range(instance.n_nodes) if i != start)
+    bit = {node: pos for pos, node in enumerate(nodes)}
+    full = (1 << len(nodes)) - 1
+    cost: dict[tuple[int, int], float] = {}
+    parent: dict[tuple[int, int], int | None] = {}
+    for node in nodes:
+        mask = 1 << bit[node]
+        cost[(mask, node)] = instance.distances.values[start][node]
+        parent[(mask, node)] = None
+    for mask in range(1, full + 1):
+        if mask.bit_count() <= 1:
+            continue
+        for endpoint in nodes:
+            ebit = 1 << bit[endpoint]
+            if not (mask & ebit):
+                continue
+            prev_mask = mask ^ ebit
+            best = inf
+            best_prev: int | None = None
+            for prev in nodes:
+                pbit = 1 << bit[prev]
+                if not (prev_mask & pbit):
+                    continue
+                candidate = cost[(prev_mask, prev)] + instance.distances.values[prev][endpoint]
+                if candidate < best or (candidate == best and (best_prev is None or prev < best_prev)):
+                    best = candidate
+                    best_prev = prev
+            cost[(mask, endpoint)] = best
+            parent[(mask, endpoint)] = best_prev
+    best_total = inf
+    end: int | None = None
+    for endpoint in nodes:
+        candidate = cost[(full, endpoint)] + instance.distances.values[endpoint][start]
+        if candidate < best_total or (candidate == best_total and (end is None or endpoint < end)):
+            best_total = candidate
+            end = endpoint
+    if end is None:
+        raise RuntimeError("Held-Karp search produced no terminal node")
+    rev: list[int] = []
+    mask = full
+    cur: int | None = end
+    while cur is not None:
+        rev.append(cur)
+        prev = parent[(mask, cur)]
+        mask ^= 1 << bit[cur]
+        cur = prev
+    route = (start, *reversed(rev), start)
+    # Recompute independently from the reconstructed route; the DP value is not trusted as output cost.
+    objective = route_cost(instance, route)
+    return TSPSolution(
+        route,
+        objective,
+        method="held-karp",
+        is_exact=True,
+        optimality_proven=True,
+        _proof_token=_INDEPENDENT_PROOF_TOKEN,
+        runtime_seconds=perf_counter() - t0,
+        metadata={"start_index": start, "states_stored": len(cost), "max_nodes": limit, "dp_objective": best_total},
+    )

solverpilot/applications/tsp/solution.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from math import isfinite
+from types import MappingProxyType
+from typing import Any, Mapping, Sequence
+
+from .errors import TSPValidationError
+
+
+_INDEPENDENT_PROOF_TOKEN = object()
+
+
+@dataclass(frozen=True, slots=True)
+class TSPSolution:
+    route: tuple[int, ...]
+    objective: float
+    method: str
+    is_exact: bool
+    optimality_proven: bool
+    runtime_seconds: float | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict, compare=False)
+
+    def __init__(
+        self,
+        route: Sequence[int],
+        objective: float,
+        *,
+        method: str,
+        is_exact: bool,
+        optimality_proven: bool,
+        runtime_seconds: float | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        _proof_token: object | None = None,
+    ) -> None:
+        normalized: list[int] = []
+        for value in route:
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise TSPValidationError("TSP route entries must be integer node indices")
+            normalized.append(int(value))
+        obj = float(objective)
+        if not isfinite(obj):
+            raise TSPValidationError("TSP objective must be finite")
+        if type(is_exact) is not bool or type(optimality_proven) is not bool:
+            raise TSPValidationError("is_exact and optimality_proven must be bool values")
+        if optimality_proven and not is_exact:
+            raise TSPValidationError("optimality_proven requires is_exact=True")
+        if optimality_proven and _proof_token is not _INDEPENDENT_PROOF_TOKEN:
+            raise TSPValidationError(
+                "independent optimality proof may only be issued by SolverPilot verified/reference paths"
+            )
+        method_value = str(method).strip()
+        if not method_value:
+            raise TSPValidationError("TSP solution method must be non-empty")
+        if runtime_seconds is not None:
+            runtime_seconds = float(runtime_seconds)
+            if not isfinite(runtime_seconds) or runtime_seconds < 0.0:
+                raise TSPValidationError("runtime_seconds must be finite and non-negative")
+        object.__setattr__(self, "route", tuple(normalized))
+        object.__setattr__(self, "objective", obj)
+        object.__setattr__(self, "method", method_value)
+        object.__setattr__(self, "is_exact", is_exact)
+        object.__setattr__(self, "optimality_proven", optimality_proven)
+        object.__setattr__(self, "runtime_seconds", runtime_seconds)
+        object.__setattr__(self, "metadata", MappingProxyType(dict(metadata or {})))

solverpilot/applications/tsp/validation.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from math import isclose, isfinite
+from typing import Sequence
+
+from .distance import route_cost
+from .model import TSPInstance
+from .solution import TSPSolution
+
+
+@dataclass(frozen=True, slots=True)
+class TSPValidationReport:
+    valid: bool
+    errors: tuple[str, ...]
+    warnings: tuple[str, ...]
+    objective_recomputed: float | None
+    objective_reported: float | None
+    objective_difference: float | None
+
+
+def validate_tsp_route(
+    instance: TSPInstance,
+    route_or_solution: Sequence[int] | TSPSolution,
+    *,
+    reported_objective: float | None = None,
+    atol: float = 1e-9,
+    rtol: float = 1e-9,
+) -> TSPValidationReport:
+    if isinstance(atol, bool) or isinstance(rtol, bool):
+        raise ValueError("TSP validation tolerances must be non-negative finite numbers")
+    atol = float(atol); rtol = float(rtol)
+    if not isfinite(atol) or not isfinite(rtol) or atol < 0.0 or rtol < 0.0:
+        raise ValueError("TSP validation tolerances must be non-negative finite numbers")
+    errors: list[str] = []
+    warnings: list[str] = []
+    if isinstance(route_or_solution, TSPSolution):
+        route = tuple(route_or_solution.route)
+        if reported_objective is None:
+            reported_objective = route_or_solution.objective
+    else:
+        try:
+            route = tuple(route_or_solution)
+        except TypeError:
+            return TSPValidationReport(False, ("route must be iterable",), (), None, reported_objective, None)
+    if len(route) != instance.n_nodes + 1:
+        errors.append(f"route must contain n_nodes + 1 entries ({instance.n_nodes + 1})")
+    normalized: list[int] = []
+    for value in route:
+        if isinstance(value, bool) or not isinstance(value, int):
+            errors.append("route entries must be integer node indices")
+            continue
+        normalized.append(int(value))
+    if len(normalized) == len(route):
+        invalid = sorted({x for x in normalized if x < 0 or x >= instance.n_nodes})
+        if invalid:
+            errors.append(f"route contains out-of-range node indices: {invalid}")
+        if normalized and normalized[0] != normalized[-1]:
+            errors.append("route must be closed")
+        if not invalid and len(normalized) >= 2:
+            interior = normalized[:-1]
+            counts = Counter(interior)
+            missing = sorted(set(range(instance.n_nodes)) - set(interior))
+            duplicated = sorted(k for k, v in counts.items() if v != 1)
+            if missing:
+                errors.append(f"route is missing nodes: {missing}")
+            if duplicated:
+                errors.append(f"route does not visit nodes exactly once: {duplicated}")
+    recomputed: float | None = None
+    if not errors:
+        recomputed = route_cost(instance, normalized)
+    reported: float | None = None
+    difference: float | None = None
+    if reported_objective is not None:
+        if isinstance(reported_objective, bool):
+            errors.append("reported objective must be numeric, not bool")
+            reported_objective = None
+        try:
+            reported = None if reported_objective is None else float(reported_objective)
+        except (TypeError, ValueError):
+            errors.append("reported objective must be numeric")
+        else:
+            if reported is None:
+                pass
+            elif not isfinite(reported):
+                errors.append("reported objective must be finite")
+            elif recomputed is not None:
+                difference = reported - recomputed
+                if not isclose(reported, recomputed, rel_tol=rtol, abs_tol=atol):
+                    errors.append("reported objective does not match independently recomputed route cost")
+    return TSPValidationReport(not errors, tuple(errors), tuple(warnings), recomputed, reported, difference)