# Beyond the First 30 Minutes: 3D Gazebo & Extension Points > Synthesis of initial learnings, bridging from 2D discrete simulation to containerized ROS 2 / Gazebo Fortress 3D worlds, running Monte Carlo benchmark evaluations against baselines, and architectural extension hooks. - Repository: ivaziz/swarm_car_search - GitHub: https://github.com/ivaziz/swarm_car_search - Human wiki: https://grok-wiki.com/public/wiki/ivaziz-swarm-car-search-66a3d00cb601 - Complete Markdown: https://grok-wiki.com/public/wiki/ivaziz-swarm-car-search-66a3d00cb601/llms-full.txt ## Source Files - `scripts/run_evaluation.py` - `evaluation/ai_benchmarks.py` - `run_gazebo_gui.sh` - `docker/Dockerfile` - `docs/thesis_chapter_swarm.md` ---
Relevant source files The following files were used as context for generating this wiki page: - [scripts/run_evaluation.py](scripts/run_evaluation.py) - [evaluation/ai_benchmarks.py](evaluation/ai_benchmarks.py) - [run_gazebo_gui.sh](run_gazebo_gui.sh) - [docker/Dockerfile](docker/Dockerfile) - [docs/thesis_chapter_swarm.md](docs/thesis_chapter_swarm.md) - [ros2_ws/src/swarm_gazebo/launch/swarm_simulation.launch.py](ros2_ws/src/swarm_gazebo/launch/swarm_simulation.launch.py) - [ros2_ws/src/swarm_gazebo/swarm_gazebo/slam_bridge.py](ros2_ws/src/swarm_gazebo/swarm_gazebo/slam_bridge.py) - [ros2_ws/src/swarm_gazebo/swarm_gazebo/perception_bridge.py](ros2_ws/src/swarm_gazebo/swarm_gazebo/perception_bridge.py) - [ros2_ws/src/swarm_gazebo/swarm_gazebo/robot_controller.py](ros2_ws/src/swarm_gazebo/swarm_gazebo/robot_controller.py) - [ros2_ws/src/swarm_gazebo/swarm_gazebo/coordinator_node.py](ros2_ws/src/swarm_gazebo/swarm_gazebo/coordinator_node.py) - [interfaces/slam_interface.py](interfaces/slam_interface.py) - [interfaces/perception_interface.py](interfaces/perception_interface.py) - [interfaces/server_interface.py](interfaces/server_interface.py) - [swarm/task_allocation/allocation_strategy.py](swarm/task_allocation/allocation_strategy.py) - [swarm/aco/aco_config.py](swarm/aco/aco_config.py) - [evaluation/baselines.py](evaluation/baselines.py) - [evaluation/metrics_collector.py](evaluation/metrics_collector.py)
# Beyond the First 30 Minutes: 3D Gazebo & Extension Points Once developers have verified the core 2D discrete simulation and understood the bio-inspired Ant Colony Optimization (ACO) coordination loop, the next engineering phase involves elevating the system into high-fidelity environments and rigorous scientific evaluation. The SwarmX architecture provides two primary pathways beyond the introductory setup: deploying into a containerized 3D physics environment powered by ROS 2 Humble and Gazebo Fortress, and executing statistical Monte Carlo comparative benchmarks against classical exploration baselines. This guide bridges the gap between discrete algorithmic prototyping and full-stack robotics engineering. It walks through containerized headless and graphical Gazebo execution on host hardware, maps the inter-process ROS 2 parameter bridge communication channels, analyzes the 15-metric comparative evaluation pipeline and 4-variant ACO ablation studies, and defines explicit architectural extension points across SLAM, perception, task allocation, and external telemetry. --- ## 1. Bridging from 2D Discrete Simulation to 3D Gazebo Fortress The fast 2D simulation uses discretized grid cells ($1.0\,\text{m}$ resolution) and forward Euler differential kinematics for rapid algorithm iteration. To test real sensor noise, continuous physics, wheel slip, and geometric line-of-sight occlusions, SwarmX provides a fully containerized ROS 2 Humble and Gazebo Fortress (Ignition) 3D simulation stack. ### 1.1 Containerized Runtime & Display Architecture To ensure cross-platform reproducibility across Linux and macOS (specifically Apple Silicon ARM64), the 3D stack is isolated inside a multi-stage Docker container. Rather than demanding complex native X11 forwarding from the host, the container incorporates a self-contained virtual display server (`Xvfb`), window manager (`fluxbox`), VNC server (`x11vnc`), and HTML5 WebSocket gateway (`websockify` + `novnc`). ``` +---------------------------------------------------------------------------------------+ | HOST MACHINE | | - Web Browser: http://localhost:6080/vnc.html (noVNC HTML5 3D View) | | - Native Screen Sharing: vnc://localhost:5900 (Apple Silicon / Desktop VNC) | +-------------------------------------------+-------------------------------------------+ | Port 6080 (WS) / Port 5900 (RFB) +-------------------------------------------v-------------------------------------------+ | DOCKER CONTAINER (swarm_gazebo:humble) | | | | +-----------------------+ +-------------------+ +-----------------------+ | | | Virtual Display | --> | fluxbox (WM) | --> | x11vnc (:1 -> 5900) | | | | Xvfb :1 1600x1000x24 | | | | websockify (:6080) | | | +-----------+-----------+ +-------------------+ +-----------------------+ | | | DISPLAY=:1 | | +-----------v-------------------------------------------------------------------+ | | | Gazebo Sim (Ignition Fortress) | | | | - 50m x 50m Urban Search World (urban_search_world.world) | | | | - Physics Engine, Differential AGV Spawners, Target Sedan (DXB-88392) | | | | - 2D LiDAR Sensors, RGB Cameras, Wheel Odometry Encoders | | | +---------------------------------------+---------------------------------------+ | | | Ignition Transport Topics | | +---------------------------------------v---------------------------------------+ | | | ROS 2 <-> Gazebo Parameter Bridge (ros_gz_bridge) | | | | - Clock, Odometry, LaserScan, RGB Images, cmd_vel Twists | | | +---------------------------------------+---------------------------------------+ | | | ROS 2 Topics (/robot_*/...) | | +---------------------------------------v---------------------------------------+ | | | SwarmX ROS 2 Orchestrator & Node Stack (MultiThreadedExecutor) | | | | - GazeboSLAMBridge (ISLAMProvider) | | | | - GazeboPerceptionBridge (Camera FOV + Fuzzy OCR Matcher) | | | | - GazeboSwarmCoordinatorNode (ACO Task Scorer + Failure Recovery) | | | | - GazeboRobotController (Closed-loop proportional waypoint navigation) | | | +-------------------------------------------------------------------------------+ | +---------------------------------------------------------------------------------------+ ``` Sources: [docker/Dockerfile:1-56](), [run_gazebo_gui.sh:15-125]() ### 1.2 Topic Plumbing & The ROS–Gazebo Parameter Bridge Communication between Gazebo Fortress physics and ROS 2 nodes is managed by `ros_gz_bridge parameter_bridge`. The bridge translates Ignition transport messages into standard ROS 2 message types across all four robot namespaces (`robot_1` through `robot_4`). | Topic Pattern | Direction | ROS 2 Message Type | Gazebo Transport Type | Functional Role | | :--- | :---: | :--- | :--- | :--- | | `/clock` | `Gz -> ROS` | `rosgraph_msgs/msg/Clock` | `ignition.msgs.Clock` | Synchronizes ROS simulation time with Gazebo physics. | | `/{rid}/cmd_vel` | `ROS -> Gz` | `geometry_msgs/msg/Twist` | `ignition.msgs.Twist` | Forward and angular velocity commands to differential drive joints. | | `/{rid}/odom` | `Gz -> ROS` | `nav_msgs/msg/Odometry` | `ignition.msgs.Odometry` | Wheel odometry state (pose estimate, linear and angular velocity). | | `/{rid}/scan` | `Gz -> ROS` | `sensor_msgs/msg/LaserScan` | `ignition.msgs.LaserScan` | Planar LiDAR range returns for obstacle mapping and frontier discovery. | | `/{rid}/camera/image_raw` | `Gz -> ROS` | `sensor_msgs/msg/Image` | `ignition.msgs.Image` | Forward-facing camera feed for vehicle detection and plate OCR. | Sources: [run_gazebo_gui.sh:127-147](), [ros2_ws/src/swarm_gazebo/launch/swarm_simulation.launch.py:29-80]() ### 1.3 Master Execution Launchers The repository supplies two entry points for 3D simulation: 1. **Host-Level Master Bash Script (`run_gazebo_gui.sh`)**: Verifies Docker daemon health, builds the container image `swarm_gazebo:humble` if missing, compiles the ROS 2 workspace using `colcon build --symlink-install`, starts Xvfb/Fluxbox/VNC inside Docker, launches `ign gazebo`, opens `http://localhost:6080/vnc.html` automatically in the host browser, and boots the Python orchestrator. ```bash ./run_gazebo_gui.sh ``` 2. **Native ROS 2 Launch Description (`swarm_simulation.launch.py`)**: Used when running directly within the sourced ROS 2 environment. Coordinates `gazebo_world.launch.py`, `slam_bridge_node`, `perception_bridge_node`, `coordinator_node`, `mission_monitor_node`, and four individual `robot_controller_node` instances. Sources: [run_gazebo_gui.sh:48-159](), [ros2_ws/src/swarm_gazebo/launch/swarm_simulation.launch.py:16-81]() --- ## 2. ROS 2 Bridge Nodes & Controller Implementation The integration cleanly wraps the core SwarmX Python library within ROS 2 nodes, ensuring zero coupling between algorithm logic and the underlying middleware. ```mermaid flowchart TD subgraph GazeboSimulation["Gazebo Fortress 3D Physics"] GZ_Clock["/clock"] GZ_Odom["/{rid}/odom"] GZ_Scan["/{rid}/scan"] GZ_Cam["/{rid}/camera/image_raw"] GZ_Cmd["/{rid}/cmd_vel"] end subgraph BridgeLayer["ROS 2 Bridge Layer"] Bridge["ros_gz_bridge parameter_bridge"] SLAMBridge["GazeboSLAMBridge (ISLAMProvider)"] PercepBridge["GazeboPerceptionBridge"] end subgraph SwarmCore["Swarm Intelligence Core"] CoordNode["GazeboSwarmCoordinatorNode"] ACO["ACOEngine & Boltzmann Softmax"] PheroMap["Tri-Layer Pheromone Field"] FaultMgr["Dynamic Failure Recovery"] end subgraph MotionControl["Motion Control Layer"] Controllers["GazeboRobotController (/robot_*/cmd_vel)"] end GZ_Clock --> Bridge GZ_Odom --> Bridge GZ_Scan --> Bridge GZ_Cam --> Bridge Bridge --> GZ_Cmd Bridge --> SLAMBridge Bridge --> PercepBridge SLAMBridge -- "SLAMState (Pose + Occupancy + Frontiers)" --> CoordNode PercepBridge -- "/swarm/perception_events" --> CoordNode CoordNode --> ACO CoordNode --> PheroMap CoordNode --> FaultMgr CoordNode -- "Assigned Waypoints" --> Controllers Controllers --> Bridge ``` ### 2.1 SLAM Bridge (`GazeboSLAMBridge`) Subscribes to `/robot_*/odom` and `/robot_*/scan`. It maintains an internal `UrbanEnvironment` representation and transforms local robot odometry into the global coordinate frame using the pre-configured spawn poses: - `robot_1`: $(6.0, 6.0, 0.0)$ - `robot_2`: $(6.0, 44.0, -\pi/2)$ - `robot_3`: $(44.0, 6.0, \pi/2)$ - `robot_4`: $(44.0, 44.0, \pi)$ It implements the `ISLAMProvider` contract, allowing `GazeboSwarmCoordinatorNode` to poll `get_latest_state(robot_id)` to extract `FrontierCluster` instances and `OccupancyGrid2D` state. ```python # ros2_ws/src/swarm_gazebo/swarm_gazebo/slam_bridge.py class GazeboSLAMBridge(ISLAMProvider, Node): def __init__(self, robot_ids: List[str], map_width_m: float = 50.0, ...): Node.__init__(self, "gazebo_slam_bridge") self.spawn_poses = spawn_poses or DEFAULT_SPAWN_POSES # Tracks local occupancy grids and frontier clusters ``` Sources: [ros2_ws/src/swarm_gazebo/swarm_gazebo/slam_bridge.py:31-110]() ### 2.2 Closed-Loop Proportional Controller (`GazeboRobotController`) Translates discrete task centroids into continuous physical motion. The controller runs at $20\,\text{Hz}$ ($\Delta t = 0.05\,\text{s}$), transforming local odometry to world coordinates, computing heading error $\Delta \theta = \text{atan2}(y_{\text{goal}} - y, x_{\text{goal}} - x) - \theta$, and applying proportional gains ($K_p^{\text{linear}} = 0.8, K_p^{\text{angular}} = 2.0$): $$v = \min(v_{\max}, K_p^{\text{linear}} \cdot d) \cdot \max(0.0, \cos(\Delta\theta))$$ $$\omega = \text{clamp}(K_p^{\text{angular}} \cdot \Delta\theta, -\omega_{\max}, \omega_{\max})$$ When the Euclidean distance to the waypoint falls below the goal tolerance ($0.8\,\text{m}$), the controller publishes task completion on `/{robot_id}/task_status` and idles until the next ACO assignment. Sources: [ros2_ws/src/swarm_gazebo/swarm_gazebo/robot_controller.py:41-120]() --- ## 3. Monte Carlo Benchmarking & Baseline Comparisons To scientifically substantiate claims regarding swarm coordination, SwarmX includes a Monte Carlo benchmarking framework in `scripts/run_evaluation.py` and scenario suites in `evaluation/ai_benchmarks.py`. ### 3.1 Comparative Strategies The benchmark compares three distinct task allocation paradigms: 1. **Proposed ACO (`ACOAllocationStrategy`)**: Evaluates frontier clusters using multi-objective stigmergic scoring (information gain, land-use detection prior, distance cost, congestion penalties, avoidance fields) and assigns tasks via scale-invariant Boltzmann Softmax ($T = 0.5$). 2. **Nearest Frontier (`NearestFrontierStrategy`)**: The classical Yamauchi greedy baseline. Selects the closest unassigned frontier purely by Euclidean distance, ignoring peer congestion, search history, and vehicle priors. 3. **Random Walk (`RandomAllocationStrategy`)**: Stochastic uncoordinated baseline that picks randomly among pending frontiers. Sources: [evaluation/baselines.py:20-46](), [swarm/task_allocation/allocation_strategy.py:38-100]() ### 3.2 The 15 Comparative Performance Metrics Telemetry is accumulated per tick across all robots by `MetricsCollector` and synthesized into a 15-metric performance matrix: | # | Metric Name | Unit / Type | Description & Calculation | | :---: | :--- | :---: | :--- | | **1** | **Target Discovery Rate** | `%` | Percentage of trials where target `DXB-88392` was verified ($C_{\text{match}} \ge 0.80$). | | **2** | **Mean Time-to-Detection (TTD)** | `s` | Average elapsed simulation time until confirmed target acquisition. | | **3** | **Median Time-to-Detection** | `s` | Median TTD across successful runs, robust to outlier runs. | | **4** | **Final Area Coverage** | `%` | Explored free grid cells as a fraction of total navigable urban area. | | **5** | **Exploration Rate** | `m²/s` | Area mapped per unit time ($\Delta \text{Area} / \Delta t$). | | **6** | **Trajectory Overlap Ratio** | `%` | Proportion of cell visits beyond the initial visit: $\frac{\sum \max(0, N_v - 1)}{\sum N_v}$. | | **7** | **Total Distance Traveled** | `m` | Cumulative odometric distance traveled by all fleet agents. | | **8** | **Battery Energy Consumed** | Units | Normalized propulsion and sensor battery consumption. | | **9** | **Tasks Completed** | Count | Total frontier exploration tasks navigated and closed. | | **10** | **Dynamic Reassignments** | Count | Task reallocations triggered by proximity shifts or failure events. | | **11** | **Failure Recovery Rate** | `%` | Percentage of injected hardware faults successfully recovered. | | **12** | **Failure Recovery Latency** | `s` | Elapsed time between robot failure injection and peer orphan task reassignment. | | **13** | **Candidate Detections** | Count | Vehicles sighted within camera FOV requiring plate inspection. | | **14** | **False Positives Rejected** | Count | Civilian decoy vehicles evaluated by OCR and discarded. | | **15** | **Target Confirmations** | Count | Verified target sightings passing temporal and appearance thresholds. | Sources: [scripts/run_evaluation.py:229-309](), [evaluation/metrics_collector.py:21-54]() ### 3.3 4-Variant ACO Ablation Studies To isolate the exact contribution of each stigmergic term in the multi-objective utility function: $$\text{Score}(t_i, r_j) = \frac{[\tau_i]^\alpha \cdot [\eta_i]^\beta \cdot [P_i]^\gamma \cdot [G_i]^\delta}{[C(r_j, t_i)]^\varepsilon \cdot [\Omega_i]^\zeta \cdot [K_i]^\theta}$$ The test runner supports an `--ablation` mode executing four configurations: | Ablation Variant | Positive Pheromone ($\alpha$) | Target Prior ($\gamma$) | Scientific Objective | | :--- | :---: | :---: | :--- | | `ACO_BASELINE` | $\alpha = 0.0$ | $\gamma = 0.0$ | Strips all domain heuristics and target recruitment; acts as pure spatial dispersion. | | `ACO_PROB_ONLY` | $\alpha = 0.0$ | $\gamma = 1.8$ | Uses land-use priors (e.g. parking zones) without dynamic stigmergic recruitment. | | `ACO_PHERO_ONLY` | $\alpha = 1.2$ | $\gamma = 0.0$ | Relies on dynamic visual cue pheromone deposits without land-use priors. | | `ACO_FULL` | $\alpha = 1.2$ | $\gamma = 1.8$ | Full proposed system combining prior maps with stigmergic peer recruitment. | Sources: [scripts/run_evaluation.py:583-608](), [docs/thesis_chapter_swarm.md:120-134]() ### 3.4 AI Benchmark Scenarios A through H Deterministic perception and coordination evaluations are encoded in `evaluation/ai_benchmarks.py` across eight scenarios: | Scenario | Code Name | Primary Challenge Tested | | :--- | :--- | :--- | | **A** | `scenario_a` | Reachable target in open central plaza. | | **B** | `scenario_b` | Partially occluded target behind building corner. | | **C** | `scenario_c` | Civilian decoy vehicles present (`AD-10294` white SUV, `SHJ-44910` red sedan). | | **D** | `scenario_d` | Poor/noisy OCR with simulated character substitutions ($B \leftrightarrow 8, O \leftrightarrow 0, Z \leftrightarrow 2$). | | **E** | `scenario_e` | Catastrophic robot failure injected on `robot_1` at tick 20. | | **F** | `scenario_f` | Cooperative multi-robot encounter requiring two-vehicle convergence. | | **G** | `scenario_g` | Distant target located in the far corner of the search boundary. | | **H** | `scenario_h` | Low-prior zone target requiring Bayesian exploration propagation. | Sources: [evaluation/ai_benchmarks.py:184-194](), [docs/thesis_chapter_swarm.md:250-280]() --- ## 4. Architectural Extension Hooks & Developer Contracts SwarmX was engineered with explicit abstract base classes (ABCs) and dataclass schemas to enable independent development across university cohorts or modular production upgrades. ```mermaid classDiagram class ISLAMProvider { <> +get_latest_state(robot_id: str) SLAMState* +is_healthy(robot_id: str) bool* } class IPerceptionProvider { <> +detect_vehicles(robot_id: str, camera_frame_id: str) VehicleDetectionEvent* +recognize_license_plate(detection: VehicleDetectionEvent) PlateDetectionEvent* +match_watchlist(plate_event: PlateDetectionEvent) MatchEvent* } class ITaskAllocationStrategy { <> +allocate_task(robot_id, robot_pose, available_tasks, swarm_state, pheromone_map, target_probability_map, search_memory, battery_level) SearchTask* } class IServerReporter { <> +report_match(report: DetectionReport) bool* +send_telemetry(telemetry: MissionReport) bool* } class GazeboSLAMBridge { +get_latest_state(robot_id: str) SLAMState +is_healthy(robot_id: str) bool } class ACOAllocationStrategy { +allocate_task(...) SearchTask } ISLAMProvider <|.. GazeboSLAMBridge : implements ITaskAllocationStrategy <|.. ACOAllocationStrategy : implements ``` ### 4.1 Extending SLAM: The `ISLAMProvider` Contract Developers integrating custom cartographer, RTAB-Map, or hardware LiDAR systems only need to implement two methods in `interfaces/slam_interface.py`: - `get_latest_state(robot_id: str) -> SLAMState`: Returns current `Pose2D`, linear/angular velocities, `OccupancyGrid2D`, and extracted `List[FrontierCluster]`. - `is_healthy(robot_id: str) -> bool`: Flags whether tracking is valid or if the robot is drifting/lost. Sources: [interfaces/slam_interface.py:69-100]() ### 4.2 Extending Perception: The `IPerceptionProvider` Contract Located in `interfaces/perception_interface.py`, this contract decouples computer vision from swarm decision making: - `detect_vehicles(robot_id, camera_frame_id) -> Optional[VehicleDetectionEvent]`: YOLO/SSD bounding box detector. - `recognize_license_plate(detection) -> Optional[PlateDetectionEvent]`: Crop OCR model returning recognized text and character confidence scores. - `match_watchlist(plate_event) -> Optional[MatchEvent]`: Fuzzy matching engine (Levenshtein distance) comparing extracted text against stolen vehicle registries. Sources: [interfaces/perception_interface.py:86-103]() ### 4.3 Implementing Custom MRTA Strategies To benchmark a new task allocation algorithm (e.g. Market-based Auctioning, Consensus-Based Bundle Algorithm / CBBA, or Deep Reinforcement Learning), subclass `ITaskAllocationStrategy` in `swarm/task_allocation/allocation_strategy.py` and register it in `evaluation/baselines.py`: ```python # swarm/task_allocation/allocation_strategy.py class ITaskAllocationStrategy(ABC): @abstractmethod def allocate_task( self, robot_id: str, robot_pose: Pose2D, available_tasks: List[SearchTask], swarm_state: Optional[SwarmState] = None, pheromone_map: Optional[PheromoneMap] = None, target_probability_map: Optional[Any] = None, search_memory: Optional[Any] = None, battery_level: float = 1.0, ) -> Optional[SearchTask]: """Selects a candidate task for the specified robot.""" pass ``` Sources: [swarm/task_allocation/allocation_strategy.py:19-36](), [evaluation/baselines.py:27-46]() ### 4.4 External Dashboard Reporting: `IServerReporter` To stream telemetry, live occupancy maps, or incident alerts to cloud dashboards, implement `IServerReporter` in `interfaces/server_interface.py`: - `report_match(report: DetectionReport) -> bool`: Dispatches target alerts containing full multi-stage confidence breakdowns and image evidence URLs. - `send_telemetry(telemetry: MissionReport) -> bool`: Emits periodic swarm health, active agent counts, and cumulative area coverage metrics. Sources: [interfaces/server_interface.py:31-43]() ### 4.5 Tuning ACO Weights via `ACOConfig` Hyperparameters can be updated programmatically or loaded dynamically via YAML using `ACOConfig.from_yaml(path)`: - Exponents: $\alpha$ (pheromone exploitation), $\beta$ (information gain), $\gamma$ (target prior), $\delta$ (urgency), $\varepsilon$ (distance penalty), $\zeta$ (congestion penalty), $\theta$ (avoidance repulsion). - Stochastic parameters: `temperature` (Boltzmann Softmax dispersion), `epsilon_greedy`, and `deterministic`. Sources: [swarm/aco/aco_config.py:10-84]() --- ## 5. Practical Operational Workflows & CLI Recipes ``` +---------------------------------------------------------------------------------------+ | OPERATIONAL RECIPES | | | | 1. Interactive 3D Gazebo GUI (Docker + noVNC Web Display): | | $ ./run_gazebo_gui.sh | | Browser opens: http://localhost:6080/vnc.html?autoconnect=true&resize=remote | | | | 2. Headless Monte Carlo Benchmark (3 Trials, Easy Target): | | $ python3 scripts/run_evaluation.py --scenario easy_target --trials 3 | | | | 3. ACO 4-Variant Ablation Study: | | $ python3 scripts/run_evaluation.py --scenario hidden_target --ablation | | | | 4. Deterministic AI Benchmark Suite (Scenarios A through H): | | $ python3 scripts/evaluate_ai_benchmarks.py | +---------------------------------------------------------------------------------------+ ``` ### Running Monte Carlo Evaluations To execute comparative trials between ACO, Nearest Frontier, and Random Walk: ```bash python3 scripts/run_evaluation.py \ --scenario easy_target \ --trials 5 \ --steps 120 \ --robots 4 \ --output-dir output/evaluation_run ``` The runner generates: - `output/evaluation_run/benchmark_results.json`: Complete raw JSON telemetry for every trial. - `output/evaluation_run/benchmark_report.md`: Markdown summary table with means, standard deviations, and recovery latencies. - `output/evaluation_run/benchmark_coverage_comparison.svg`: Pure-Python vector graphic showing exploration curves over time. - `output/evaluation_run/coverage_comparison.png` & `metrics_comparison.png`: Publication-grade PNG charts when Matplotlib is available. Sources: [scripts/run_evaluation.py:62-83](), [scripts/run_evaluation.py:634-658]() ### Running ACO Ablation Experiments To test the individual effects of pheromone recruitment and prior probability weighting: ```bash python3 scripts/run_evaluation.py --ablation --trials 5 --scenario hidden_target ``` Sources: [scripts/run_evaluation.py:583-608]() --- ## 6. Compound Knowledge Profile & Architecture Governance This documentation and architectural review synthesizes learnings using Every's Compound Engineering methodology (adapted for provider-neutral Blueprint, Page Shape, and QA Review workflows): - **Provider Neutrality & BYOC/BYOK**: All interfaces, bridges, and benchmark runners operate locally and independently of hosted cloud vendors or proprietary model APIs. Perception interfaces consume local vision models (or synthetic mocks), and ROS 2 middleware communicates over standard DDS/Ignition transport protocols. - **Portability Across Runtimes**: Whether evaluated in discrete Python 2D simulation (`simulation/environment.py`), continuous 3D Gazebo Fortress (`ros2_ws/src/swarm_gazebo`), or physical embedded robotic platforms (such as TurtleBot3 or custom differential drive AGVs), the coordination layer depends solely on abstract interface definitions (`ISLAMProvider`, `IPerceptionProvider`, `ITaskAllocationStrategy`). --- ## Summary Moving beyond the initial 30 minutes in the SwarmX codebase transitions developers from discrete 2D simulation to containerized 3D physical verification and rigorous statistical benchmarking. By leveraging `run_gazebo_gui.sh` and Docker, engineers can inspect continuous robot navigation, raycasted line-of-sight occlusion, and camera perception in Gazebo Fortress without host dependency pollution. Concurrently, the Monte Carlo benchmarking harness (`run_evaluation.py`) and clean interface abstractions (`ISLAMProvider`, `IPerceptionProvider`, `ITaskAllocationStrategy`) empower researchers to extend perception, swap SLAM algorithms, test novel MRTA schedulers, and publish empirical evaluations across standardized urban scenarios.