Source code for brushline.monitoring.mission

"""Corridor-graph UAV/LiDAR mission simulation."""

from __future__ import annotations

from datetime import UTC, datetime
from typing import Literal

from pydantic import BaseModel, ConfigDict, Field

MISSION_SCHEMA_VERSION: Literal["brushline.monitoring-mission.v1"] = (
    "brushline.monitoring-mission.v1"
)


[docs] class MissionError(ValueError): """Raised when a mission input is inconsistent."""
[docs] class MissionNode(BaseModel): """One corridor-graph node. Parameters ---------- node_id : str Node id. x_m : float X coordinate. y_m : float Y coordinate. """ model_config = ConfigDict(extra="forbid", frozen=True) node_id: str = Field(min_length=1) x_m: float y_m: float
[docs] class MissionEdge(BaseModel): """One undirected corridor-graph edge. Parameters ---------- start_id : str Start node. end_id : str End node. length_m : float Length. """ model_config = ConfigDict(extra="forbid", frozen=True) start_id: str = Field(min_length=1) end_id: str = Field(min_length=1) length_m: float = Field(gt=0)
[docs] class MissionRequest(BaseModel): """A monitor mission request. Parameters ---------- request_id : str Request id. required_node_ids : list of str Nodes that must be covered. weather_open : bool Whether the weather window is open. """ model_config = ConfigDict(extra="forbid", frozen=True) request_id: str = Field(min_length=1) required_node_ids: list[str] = Field(min_length=1) weather_open: bool = True
[docs] class MissionConfig(BaseModel): """Mission settings. Parameters ---------- start_node_id : str Start node. endurance_minutes : float Flight endurance. speed_m_per_min : float Travel speed. sensor_footprint_m : float Sensor footprint radius. cost_per_minute : float Flight cost. fixed_cost : float Fixed mission cost. """ model_config = ConfigDict(extra="forbid", frozen=True) start_node_id: str = Field(min_length=1) endurance_minutes: float = Field(default=45, gt=0) speed_m_per_min: float = Field(default=300, gt=0) sensor_footprint_m: float = Field(default=50, gt=0) cost_per_minute: float = Field(default=5, ge=0) fixed_cost: float = Field(default=100, ge=0)
[docs] class MissionPlan(BaseModel): """A feasible or blocked mission. Parameters ---------- schema_version : {"brushline.monitoring-mission.v1"} Schema version. plan_id : str Plan id. request_id : str Request id. node_order : list of str Visited node order. covered_node_ids : list of str Covered nodes. route_length_m : float Route length. flight_minutes : float Flight time. cost : float Cost. feasible : bool Endurance/weather/route feasibility. reason : str Explanation. created_utc : datetime Timezone-aware time. """ model_config = ConfigDict(extra="forbid", frozen=True) schema_version: Literal["brushline.monitoring-mission.v1"] = MISSION_SCHEMA_VERSION plan_id: str request_id: str node_order: list[str] covered_node_ids: list[str] route_length_m: float = Field(ge=0) flight_minutes: float = Field(ge=0) cost: float = Field(ge=0) feasible: bool reason: str created_utc: datetime
[docs] def build_mission_plan( *, plan_id: str, nodes: list[MissionNode], edges: list[MissionEdge], request: MissionRequest, config: MissionConfig, created_utc: datetime | None = None, ) -> MissionPlan: """Build a deterministic nearest-neighbour mission and check feasibility. Parameters ---------- plan_id : str Plan id. nodes : list of MissionNode Nodes. edges : list of MissionEdge Edges. request : MissionRequest Request. config : MissionConfig Settings. created_utc : datetime, optional Creation time. Returns ------- MissionPlan Mission plan. """ node_map = {node.node_id: node for node in nodes} if len(node_map) != len(nodes): raise MissionError("mission nodes must be unique") if config.start_node_id not in node_map: raise MissionError("start node is unknown") for node_id in request.required_node_ids: if node_id not in node_map: raise MissionError(f"required node {node_id!r} is unknown") adjacency: dict[str, list[tuple[str, float]]] = {} for edge in edges: if edge.start_id not in node_map or edge.end_id not in node_map: raise MissionError("edge references an unknown node") adjacency.setdefault(edge.start_id, []).append((edge.end_id, edge.length_m)) adjacency.setdefault(edge.end_id, []).append((edge.start_id, edge.length_m)) remaining = set(request.required_node_ids) order = [config.start_node_id] route = 0.0 current = config.start_node_id while remaining: options = sorted( (distance, target) for target in remaining if target in _reachable(current, adjacency) for distance in [_shortest(adjacency, current, target)] if distance is not None ) if not options: break distance, target = options[0] route += distance order.append(target) remaining.remove(target) current = target flight = route / config.speed_m_per_min feasible = request.weather_open and not remaining and flight <= config.endurance_minutes reason = "feasible" if not request.weather_open: reason = "weather window is closed" elif remaining: reason = "required nodes are unreachable" elif flight > config.endurance_minutes: reason = "endurance exceeded" return MissionPlan( plan_id=plan_id, request_id=request.request_id, node_order=order, covered_node_ids=order[1:] if feasible else [], route_length_m=route, flight_minutes=flight, cost=config.fixed_cost + flight * config.cost_per_minute, feasible=feasible, reason=reason, created_utc=created_utc or datetime.now(UTC), )
def _distance(left: MissionNode, right: MissionNode) -> float: return float(((left.x_m - right.x_m) ** 2 + (left.y_m - right.y_m) ** 2) ** 0.5) def _reachable(node_id: str, adjacency: dict[str, list[tuple[str, float]]]) -> set[str]: seen = {node_id} stack = [node_id] while stack: current = stack.pop() for neighbour, _ in adjacency.get(current, []): if neighbour not in seen: seen.add(neighbour) stack.append(neighbour) return seen def _shortest( adjacency: dict[str, list[tuple[str, float]]], start: str, target: str ) -> float | None: distances: dict[str, float] = {start: 0.0} unvisited = {start} while unvisited: current = min(unvisited, key=lambda item: distances[item]) unvisited.remove(current) if current == target: return distances[current] for neighbour, weight in adjacency.get(current, []): candidate = distances[current] + weight if candidate < distances.get(neighbour, float("inf")): distances[neighbour] = candidate unvisited.add(neighbour) return None __all__ = [ "MISSION_SCHEMA_VERSION", "MissionConfig", "MissionEdge", "MissionError", "MissionNode", "MissionPlan", "MissionRequest", "build_mission_plan", ]