# First Execution, Scenarios & Runtime Boundaries > Hands-on guide to launching deterministic simulation scenarios (A through F), inspecting generated visual artifacts (ASCII HUD, SVG snapshots, Matplotlib panels), and understanding environment setup constraints and dependencies. - 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_simulation.py` - `simulation/scenarios.py` - `requirements.txt` - `docs/SETUP_AND_EXECUTION.md` - `visualization/swarm_visualizer.py` ---
Relevant source files The following files were used as context for generating this wiki page: - [scripts/run_simulation.py](scripts/run_simulation.py) - [simulation/scenarios.py](simulation/scenarios.py) - [requirements.txt](requirements.txt) - [docs/SETUP_AND_EXECUTION.md](docs/SETUP_AND_EXECUTION.md) - [visualization/swarm_visualizer.py](visualization/swarm_visualizer.py) - [scripts/main.py](scripts/main.py) - [evaluation/ai_benchmarks.py](evaluation/ai_benchmarks.py)
# First Execution, Scenarios & Runtime Boundaries This guide provides a comprehensive walkthrough for onboarding, configuring, and executing deterministic simulation missions in **SwarmX** (`ivaziz/swarm_car_search`). The repository simulates a decentralized multi-robot fleet deployed across an urban street grid to detect, track, verify, and report a target vehicle using Ant Colony Optimization (ACO) task allocation, multi-layer stigmergic pheromone maps, and a multi-stage optical perception pipeline. Whether executing on a minimal standard Python runtime without third-party packages or within a full containerized ROS 2 and Gazebo Fortress environment, this document outlines the exact boundary constraints, CLI flags, deterministic benchmark scenarios (A through F, as well as extended scenarios G and H), and inspection procedures for generated visual artifacts including ASCII HUDs, pure-Python SVG vector snapshots, and publication-grade Matplotlib diagnostic dashboards. --- ## 1. Runtime Boundaries & System Architecture SwarmX is designed around a **zero-dependency core** philosophy: standard system Python is sufficient to execute the multi-agent coordination logic, simulated kinematics, sensor raycasting, perception verification, and vector visualization. High-fidelity graphical rendering and containerized physical physics form optional outer layers. ```mermaid flowchart TD subgraph Core ["Zero-Dependency Pure-Python Core (Python >= 3.9)"] CLI["CLI Entry Points\nscripts/main.py\nscripts/run_simulation.py"] Coord["Swarm Coordinator\nswarm/core/swarm_coordinator.py"] ACO["ACO Task Allocation & Stigmergy\nswarm/aco/ & swarm/pheromone/"] FSM["Robot Agents & Kinematics\nswarm/core/robot_agent.py\nswarm/states/"] Perception["Perception & OCR Pipeline\nperception/vehicle_detector.py\nperception/matching_engine.py"] VizPure["Zero-Dependency Visualizers\nrender_ascii_map (Terminal HUD)\nrender_svg_map (Pure-Python SVG)"] end subgraph OptionalEnhancements ["Optional Enhancement Layer (requirements.txt)"] Matplotlib["Matplotlib >= 3.7.0 & NumPy >= 1.24.0\nrender_matplotlib_dashboard\n3-Panel Mission Analytics"] Pillow["Pillow >= 10.0.0\nswarm_mission_animation.gif\nMulti-Frame Animated GIF"] PyTest["PyTest >= 7.0.0\nAutomated Verification Suite"] end subgraph ContainerizedLayer ["Containerized 3D Physical Simulation (Docker)"] ROS2["ROS 2 Humble Node Orchestrator\nros2_ws/src/swarm_gazebo"] Gazebo["Ignition Gazebo Fortress\nurban_search_world.world"] Bridge["ros_gz_bridge\n/clock, /cmd_vel, /odom, /scan, /camera"] VNC["Web GUI (Port 6080: noVNC)\nNative Screen Sharing (Port 5900: VNC)"] end CLI --> Coord Coord --> ACO Coord --> FSM FSM --> Perception Coord --> VizPure Coord -.-> Matplotlib Matplotlib -.-> Pillow CLI -.-> ROS2 ROS2 <--> Bridge <--> Gazebo Gazebo --> VNC ``` ### Dependency Isolation & Capabilities Matrix The runtime dynamically inspects library availability at import time and gracefully falls back to core features without crashing. | Runtime Tier | External Dependencies | Supported Features | Primary Entry Point | | :--- | :--- | :--- | :--- | | **Core Minimal** | *None* (Python standard library only) | 2D kinematic simulation, ACO allocation, tri-layer pheromone maps, OCR fuzzy matching, terminal ASCII HUD, pure-Python SVG export. | `python3 scripts/run_simulation.py` | | **Visualization Tier** | `matplotlib>=3.7.0`, `numpy>=1.24.0`, `pillow>=10.0.0` | High-resolution 3-panel dashboard (`.png`), telemetry timeline curves, belief heatmaps, animated GIF generation. | `python3 scripts/run_simulation.py` | | **Testing & Benchmark** | `pytest>=7.0.0`, `pytest-cov>=4.0.0` | Execution of all unit and integration tests across SLAM, ACO, perception, and visualizer modules. | `pytest -v` or `python3 scripts/main.py test` | | **Containerized 3D** | Docker Desktop / Docker Engine (Ubuntu 22.04 LTS, ROS 2 Humble, Gazebo Fortress) | Full rigid-body physics, 3D LiDAR pointclouds, synthetic camera sensors, noVNC web streaming (port 6080), native VNC (port 5900). | `./run_gazebo_gui.sh` or `./run_simulation.sh` | Sources: [requirements.txt:1-28](), [docs/SETUP_AND_EXECUTION.md:8-35](), [visualization/swarm_visualizer.py:22-44]() --- ## 2. Quickstart & Simulation Execution Missions can be launched either via the unified command launcher (`scripts/main.py`) or directly through the specialized simulation runner (`scripts/run_simulation.py`). ### Unified CLI Entry Point The master CLI dispatches subcommands for simulation, benchmarking, testing, and architecture inspection: ```bash # Display system architecture, developer specifications, and module inventory python3 scripts/main.py info # Execute the automated verification test suite python3 scripts/main.py test # Launch an autonomous swarm simulation run python3 scripts/main.py sim --scenario easy_target --robots 4 --steps 120 ``` Sources: [scripts/main.py:20-65](), [scripts/main.py:91-124]() ### Direct Simulation Runner Options `scripts/run_simulation.py` accepts parameters controlling the physical grid, fleet composition, target characteristics, fault injection, and output frequency: ```bash python3 scripts/run_simulation.py \ --scenario easy_target \ --robots 4 \ --steps 100 \ --output-dir output/simulation_run \ --render-every 10 \ --seed 42 ``` #### CLI Configuration Parameter Reference | Flag | Type | Default | Description | | :--- | :---: | :---: | :--- | | `--scenario` | `str` | `"easy_target"` | Named deterministic scenario (`easy_target`, `hidden_target`, `target_recruitment`, `failure_recovery`, `false_positive`, `multiple_vehicles`, or `custom`). | | `--width` | `float` | `50.0` | Urban grid width in meters. | | `--height` | `float` | `50.0` | Urban grid height in meters. | | `--resolution` | `float` | `1.0` | Grid occupancy resolution in meters per cell. | | `--robots` | `int` | `4` | Number of autonomous search robots deployed in the fleet. | | `--steps` | `int` | `100` | Maximum discrete simulation execution ticks. | | `--dt` | `float` | `0.2` | Kinematic and physics integration timestep in seconds ($0.2\,\text{s} = 5\,\text{Hz}$). | | `--target-x` | `float` | `25.0` | World X coordinate for custom target placement. | | `--target-y` | `float` | `25.0` | World Y coordinate for custom target placement. | | `--target-plate` | `str` | `"DXB-88392"` | Expected license plate string for target vehicle identification. | | `--inject-failure-tick`| `int` | `None` | Simulation tick index at which catastrophic failure is triggered on a robot. | | `--fail-robot` | `str` | `"robot_1"` | Identifier of the specific robot to disable during fault injection. | | `--output-dir` | `str` | `"output/simulation_run"` | Target filesystem directory for saving SVG frames, PNG dashboards, and reports. | | `--render-every` | `int` | `10` | Frequency in ticks for writing visual frames to disk ($10 \times 0.2\,\text{s} = 2.0\,\text{s}$). | | `--seed` | `int` | `42` | Random number generator seed for deterministic repeatability. | Sources: [scripts/run_simulation.py:47-67]() --- ## 3. Deterministic Scenarios (A through F & Extensions) To evaluate multi-robot search behavior under controlled, reproducible conditions, SwarmX provides pre-configured benchmark scenarios implemented in `simulation/scenarios.py`. ### The Canonical Urban Grid & Fleet Initial Conditions Unless overridden, all scenarios instantiate a canonical $50\,\text{m} \times 50\,\text{m}$ urban environment featuring perimeter boundary walls and four solid building blocks dividing the world into cardinal avenues and a central plaza: - **South-West Block**: $[10.0, 22.5] \times [10.0, 22.5]\,\text{m}$ - **South-East Block**: $[27.5, 40.0] \times [10.0, 22.5]\,\text{m}$ - **North-West Block**: $[10.0, 22.5] \times [27.5, 40.0]\,\text{m}$ - **North-East Block**: $[27.5, 40.0] \times [27.5, 40.0]\,\text{m}$ The four robots spawn at obstacle-free corner intersections oriented toward the interior corridors: 1. `robot_1`: $(6.0, 6.0, 0.0\,\text{rad})$ — South-West corner facing East. 2. `robot_2`: $(6.0, 44.0, -\frac{\pi}{2}\,\text{rad})$ — North-West corner facing South. 3. `robot_3`: $(44.0, 6.0, \frac{\pi}{2}\,\text{rad})$ — South-East corner facing North. 4. `robot_4`: $(44.0, 44.0, \pi\,\text{rad})$ — North-East corner facing West. Sources: [simulation/scenarios.py:37-54](), [simulation/scenarios.py:71-77]() ``` (0, 50) +---------------------------------------+ (50, 50) | R2 [v] Avenue N [<] R4| | +-------+ +-------+ | | | NW | | NE | | | | Block | | Block | | | +-------+ +-------+ | | Ave W Central Plaza Ave E | | (25, 25) | | +-------+ +-------+ | | | SW | | SE | | | | Block | | Block | | | +-------+ +-------+ | | R1 [>] Avenue S [^] R3| (0,0) +---------------------------------------+ (50, 0) ``` ### Comparative Scenario Matrix | Scenario Name | Canonical ID | Target Location | Vehicle Distribution | Max Steps / Seed | Primary Evaluation Objective | | :--- | :---: | :---: | :--- | :---: | :--- | | `easy_target` | **Scenario A** | $(25.0, 25.0)$ Central Plaza | 1 target sedan (`DXB-88392`) | 500 / 100 | Baseline convergence, unoccluded visual detection, fast discovery. | | `hidden_target` | **Scenario B** | $(45.0, 35.0)$ East Corridor | 1 target sedan (`DXB-88392`) | 600 / 105 | Raycast occlusion by buildings, peripheral navigation. | | `multiple_decoys` / `false_positive` | **Scenario C** | $(25.0, 25.0)$ Central Hub | 1 target sedan + 3 civilian decoys (`AD-10294`, `SHJ-44910`, `DXB-99112`) | 500 / 110 | Rejection of non-target vehicles via fuzzy OCR plate matching. | | `noisy_ocr` | **Scenario D** | $(25.0, 35.0)$ North Lane | 1 target sedan (`DXB-88392`) | 500 / 115 | Optical noise, character ambiguity, multi-frame temporal voting. | | `failure_recovery` | **Scenario E** | $(25.0, 25.0)$ Central Plaza | 1 target sedan (`DXB-88392`) | 500 / 120 | Robot 1 fails at $t=4.0\,\text{s}$ (tick 20); task reclamation & ACO re-allocation. | | `cooperative_encounter` / `target_recruitment` | **Scenario F** | $(25.0, 35.0)$ North Avenue | 1 target sedan (`DXB-88392`) | 600 / 125 | Multi-robot convergence, stigmergic recruitment pheromone ($\tau_s$). | | `far_target` *(Extended)* | **Scenario G** | $(35.0, 25.0)$ East Sector | 1 target sedan (`DXB-88392`) | 1500 / 130 | Distant travel; all 4 robots spawn clustered in South-West corner. | | `low_prior_target` *(Extended)* | **Scenario H** | $(6.0, 25.0)$ West Lane | 1 target sedan (`DXB-88392`) | 1000 / 135 | Deceptive high prior ($0.90$) at center; target hidden in low prior ($0.20$) zone. | Sources: [simulation/scenarios.py:56-282]() ### Detailed Scenario Specifications #### Scenario A (`easy_target`): Central Plaza Baseline Target vehicle `DXB-88392` (dark gray sedan) is parked in the center intersection at $(25.0, 25.0)$, inside a designated `central_plaza` zone $([20, 20] \times [30, 30]\,\text{m})$ with an initial prior probability of $0.85$. Robots moving inward along avenues achieve rapid line-of-sight. Sources: [simulation/scenarios.py:79-98]() ```python # simulation/scenarios.py:81-98 target = TargetVehicle( target_id="target_car_alpha", plate_number=target_plate, vehicle_class="sedan", color="dark_gray", position=(25.0, 25.0), is_stolen=True, ) return ScenarioConfig( name=name, description="Scenario A: Target easy to detect in central intersection.", target_plate=target_plate, vehicles=[target], start_poses=default_starts, max_steps=500, seed=100, zones=[UrbanZone("central_plaza", (20.0, 20.0, 30.0, 30.0), 0.85)], ) ``` #### Scenario B (`hidden_target`): East Corridor Occlusion The target is positioned at $(45.0, 35.0)$ tucked along the narrow eastern building corridor. Robots crossing the central avenue cannot observe it due to raycast obstruction by the North-East building block until reaching coordinates $x \ge 40.0\,\text{m}$. Sources: [simulation/scenarios.py:100-119]() #### Scenario C (`multiple_vehicles` / `false_positive`): Decoy Rejection To evaluate precision against false alarms, three non-stolen civilian vehicles are placed in the environment alongside the stolen car: - `decoy_suv_1`: White SUV, plate `AD-10294` at $(10.0, 25.0)$ - `decoy_sedan_2`: Red sedan, plate `SHJ-44910` at $(40.0, 25.0)$ - `decoy_truck_3`: Blue truck, plate `DXB-99112` at $(25.0, 10.0)$ The perception pipeline must classify and dismiss these vehicles as negative candidates without halting the global search. Sources: [simulation/scenarios.py:121-164]() #### Scenario D (`noisy_ocr`): Optical Degradation The target is placed at $(25.0, 35.0)$. The plate recognizer introduces optical noise and character substitutions, requiring the temporal tracker to accumulate multiple consecutive observations to reach the composite confirmation threshold ($C_{\text{target}} \ge 0.80$). Sources: [simulation/scenarios.py:166-185]() #### Scenario E (`failure_recovery`): Dynamic Fault Injection Robot `robot_1` experiences a catastrophic simulated motor failure at tick 20 ($t = 4.0\,\text{s}$). The swarm coordinator marks `robot_1` as an obstacle, revokes its pending tasks, and reallocates them to surviving members using ACO utility bidding. Sources: [simulation/scenarios.py:187-208]() #### Scenario F (`cooperative_encounter` / `target_recruitment`): Multi-Robot Convergence Target placed at $(25.0, 35.0)$ on the North avenue. Upon initial candidate sighting by the first robot, recruitment pheromone ($\tau_s$) is deposited on the shared stigmergy field, prompting nearby peers to alter trajectories for multi-angle visual confirmation. Sources: [simulation/scenarios.py:210-229]() --- ## 4. Visual Artifacts & Diagnostic Telemetry During and upon conclusion of a simulation run, `SwarmVisualizer` (`visualization/swarm_visualizer.py`) generates artifacts across three complementary formats. ### 1. Terminal ASCII HUD (`render_ascii_map`) Printed directly to `sys.stdout` during execution and in the post-mission summary, requiring zero external libraries. It maps physical space onto a character matrix with an active status header and legend. ```text === Swarm Urban Search Map [t=24.0s | Active: 4 | Target: SEARCHING] === #.................................................# #.R...............................................# #.................................................# #..........#############...#############..........# #..........#############...#############..........# #..........#############...#############..........# #..........#############...#############..........# #..........#############...#############..........# #....................?............................# #....................V............................# #.......................................R.........# #..........#############...#############..........# #..........#############...#############..........# #..........#############...#############..........# #..........#############...#############..........# #..........#############...#############..........# #.................................................# #........R........................................# #............................................R....# #.................................................# Legend: [#] Obstacle [.] Free Space [R] Robot [X] Failed Robot [?] Frontier Task [V] Vehicle [!] Target Confirmed ``` Sources: [visualization/swarm_visualizer.py:418-480]() ### 2. Pure-Python SVG Snapshots (`render_svg_map`) Self-contained vector files saved to `/frame_XXXX.svg` and `final_mission_summary.svg` with zero third-party dependencies: - **Urban Canvas**: `#16161D` background with `#1F1F28` bounds and `#3C3C4D` obstacle boxes. - **Frontier Tasks**: Rendered as dashed circles (`#FFD600` for pending, `#00E5FF` for assigned). - **Vehicles**: Squares (`#FF3D00` for wanted candidates, `#00E676` for verified target) annotated with license plate labels. - **Robot Fleets**: Directed circles colored by finite state machine status (`STATE_COLOR_MAP`), with orientation vectors indicating instantaneous heading. Failed robots are struck through with a red cross (`#F44336`). Sources: [visualization/swarm_visualizer.py:46-59](), [visualization/swarm_visualizer.py:481-576]() ### 3. Publication-Grade Matplotlib Dashboard (`render_matplotlib_dashboard`) When `matplotlib` and `numpy` are installed, SwarmX automatically configures a headless `Agg` backend (`MPLCONFIGDIR=/tmp/matplotlib_swarm_cache`) and exports high-resolution 160 DPI dashboards: ``` +----------------------------------------+---------------------------------------+ | | PANEL 2: STIGMERGY & BAYESIAN BELIEF | | | 2D RGB Heatmap of Pheromone Fields: | | PANEL 1: MAIN URBAN MAP | - Blue/Cyan : Exploration Layer (tau_e)| | - Static grid obstacles & avenue lines | - Red : Avoidance Layer (tau_a) | | - Frontier task circles (? / ID) | - Gold/Yel : Bayesian Target Belief | | - Target vehicle markers (Wanted/Found)| | | - Robot position glyphs & headings +---------------------------------------+ | - Historic breadcrumb trails (:) | PANEL 3: TELEMETRY & PROGRESS | | - Translucent 90-deg FOV vision wedges | - Exploration Coverage Curve (%) | | | - Real-time Mission State Badge | | | - 5-Stage Multi-Stage Confidence HUD | +----------------------------------------+---------------------------------------+ ``` Sources: [visualization/swarm_visualizer.py:98-142](), [visualization/swarm_visualizer.py:285-412]() ### 4. Animated GIF Compilation When `Pillow` is installed, sequential PNG frames saved every `--render-every` ticks are compiled into `/swarm_mission_animation.gif` at 4 FPS ($250\,\text{ms}$ duration per frame), visualizing the full search trajectory. Sources: [scripts/run_simulation.py:304-320]() ### 5. Post-Mission Debrief Report At the end of execution, `scripts/run_simulation.py` logs an operational summary: ```text ============================================================================ MISSION DEBRIEF REPORT ============================================================================ Scenario : easy_target Total Simulation Time : 24.0 seconds (Wall clock: 0.82s) Exploration Coverage : 64.2% Completed Tasks : 14 Reassignment Events : 2 Failed Robots Handled : 0 Recovered Orphan Tasks: 0 Vehicle Detections : 3 visual sighting(s) False Positives Disc. : 0 non-target vehicle(s) rejected Target Confirmations : 1 Target Vehicle Status : 🎯 TARGET CONFIRMED & REPORTED - Target Plate : DXB-88392 - Discovered By : robot_3 - Discovery Time : 22.4 s - Match Confidence : 94.6% - Physical Location : (25.0, 25.0) ============================================================================ ``` Sources: [scripts/run_simulation.py:336-360]() --- ## 5. Verification & Fault-Tolerant Execution Flow The simulation execution sequence coordinates perception, allocation, kinematics, and dynamic fault recovery in a tight discrete loop: ```mermaid sequenceDiagram autonumber participant Runner as scripts/run_simulation.py participant Coord as SwarmCoordinator participant FailDet as FailureDetector participant ACO as ACOAllocationStrategy participant Robot as RobotAgent (Fleet) participant Viz as SwarmVisualizer Runner->>Coord: setup_simulation(args) Coord->>Robot: register_robot(agent_1..4) loop Every Simulation Tick (dt = 0.2s) opt Tick == inject_failure_tick Runner->>Coord: simulate_robot_failure(robot_id, reason) Coord->>FailDet: mark_failed(robot_id) Coord->>ACO: recover_orphaned_tasks(robot_id) ACO-->>Coord: tasks returned to PENDING pool end Coord->>Robot: step_coordination(timestamp, dt) Robot->>Robot: Update SLAM & Raycast FOV opt Vehicle Detected in FOV Robot->>Robot: Plate OCR & Fuzzy String Match opt Match Score >= Threshold Robot->>Coord: report_target_found(plate, pose, confidence) Coord->>Coord: Deposit Recruitment Pheromone (tau_s) end end Coord->>ACO: evaluate_frontier_tasks() opt Tick % render_every == 0 Coord->>Viz: render_svg_map() opt Matplotlib Available Coord->>Viz: render_matplotlib_dashboard() end end end Runner->>Viz: render_ascii_map() & save final summaries ``` ### Dynamic Robot Failure Injection Mechanics When `--inject-failure-tick` is reached (such as tick 20 in Scenario E), `coordinator.simulate_robot_failure()` triggers the following recovery pipeline: 1. **Status Transition**: The target robot state changes to `RobotState.FAILED` with motor actuation arrested ($v=0, \omega=0$). 2. **Obstacle Registration**: The failed robot pose is added to the urban environment grid as a physical obstacle cell to prevent collisions by peer robots. 3. **Task Harvesting**: Any task currently marked as `TaskStatus.ASSIGNED` to the failed robot is immediately revoked, reset to `TaskStatus.PENDING`, and submitted to the ACO bidding queue. 4. **Pheromone Redistribution**: Local avoidance pheromone ($\tau_a$) is cleared to permit surviving agents to service the abandoned sector. Sources: [scripts/run_simulation.py:219-229](), [simulation/scenarios.py:187-208](), [visualization/swarm_visualizer.py:251-254]() ### Automated Verification & Benchmark Testing The test suite and benchmark harness validate all components against baseline requirements: ```bash # Run unit and integration tests (including visualizer and simulation runner tests) pytest tests/test_visualization.py -v # Run the full 8-scenario AI benchmark evaluation suite python3 scripts/evaluate_ai_benchmarks.py ``` `evaluate_ai_benchmarks.py` runs Scenarios A through H in sequence, computing global metrics including precision ($100\%$), recall ($100\%$), average OCR character accuracy ($96.5\%$), average inference latency ($< 1.0\,\text{ms}$), and swarm exploration coverage, exporting results to `output/ai_benchmark_report.json`. Sources: [tests/test_visualization.py:29-163](), [evaluation/ai_benchmarks.py:182-263](), [scripts/evaluate_ai_benchmarks.py:20-100]() --- ## Summary SwarmX provides a completely reproducible simulation platform for multi-agent urban target search. Developers can begin in under two minutes using standard Python (`python3 scripts/run_simulation.py --scenario easy_target`) to observe decentralized ACO task allocation, stigmergic pheromone diffusion, and multi-stage vehicle identification through terminal ASCII HUDs and SVG maps. Adding optional graphical dependencies enables rich Matplotlib dashboard telemetry and animated GIF generation, while containerized Docker launchers extend the exact same coordination logic into 3D ROS 2 and Gazebo Fortress worlds.