GAMMS: Graph based Adversarial Multiagent Modeling Simulator

As intelligent systems and multi-agent coordination become increasingly central to real-world applications, there is a growing need for simulation tools that are both scalable and accessible. Existing high-fidelity simulators, while powerful, are often computationally expensive and ill-suited for rapid prototyping or large-scale agent deployments. We present GAMMS (Graph based Adversarial Multiagent Modeling Simulator), a lightweight yet extensible simulation framework designed to support fast development and evaluation of agent behavior in environments that can be represented as graphs. GAMMS emphasizes five core objectives: scalability, ease of use, integration-first architecture, fast visualization feedback, and real-world grounding. It enables efficient simulation of complex domains such as urban road networks and communication systems, supports integration with external tools (e.g., machine learning libraries, planning solvers), and provides built-in visualization with minimal configuration. GAMMS is agnostic to policy type, supporting heuristic, optimization-based, and learning-based agents, including those using large language models. By lowering the barrier to entry for researchers and enabling high-performance simulations on standard hardware, GAMMS facilitates experimentation and innovation in multi-agent systems, autonomous planning, and adversarial modeling. The framework is open-source and available at https://github.com/GAMMSim/GAMMS/

💡 Research Summary

The paper introduces GAMMS (Graph based Adversarial Multi‑agent Modeling Simulator), a lightweight yet extensible simulation framework designed to bridge the gap between high‑fidelity robotics simulators and low‑fidelity prototyping tools. The authors argue that existing high‑fidelity platforms such as Gazebo or Isaac Sim provide realistic physics and sensor models but are computationally expensive, require specialized hardware, and are cumbersome to scale to thousands of agents. Conversely, low‑fidelity agent‑based frameworks (e.g., Mesa, Repast, NetLogo) are easy to use but lack native support for graph‑structured environments common in robotics, transportation, and communication domains, and they often reside outside the Python ecosystem, making integration with modern machine‑learning libraries difficult.

GAMMS is built around five core objectives: (1) Scalability – the ability to simulate large graphs (≥ 1,000 nodes) and thousands of agents on commodity hardware; (2) Ease of Use – a minimal Python‑centric API that requires only a few lines of code to load a graph, instantiate agents, and run a scenario; (3) Integration‑First Architecture – explicit design for seamless plugging of external tools such as PyTorch, TensorFlow, Gurobi, or custom LLM planners; (4) Fast Visualization Feedback – built‑in real‑time dashboards (Matplotlib/Plotly) and structured JSON logs for post‑hoc analysis; and (5) Real‑World Grounding – native pipelines to ingest OpenStreetMap, GIS shapefiles, or other spatial data and translate them into graph representations with realistic attributes (traffic signals, road capacities, latency, etc.).

The system’s design principles are articulated as follows: a minimal set of maintained interfaces (everything is a file), a design‑by‑contract approach that formalizes input/output expectations for each component, an intermediate representation for internal modules that do not expose strict contracts (e.g., the state recorder), and a single point of access embodied by a global Context object that centralizes simulation state, mirroring the successful “CUDA context” pattern. Although Python is chosen for its low learning curve and extensive ecosystem, the authors acknowledge its performance limitations and mitigate them through optional Cython/Numba extensions and C++ back‑ends for hot paths (e.g., graph traversal, state compression).

The API is deliberately straightforward. Users can load an OSM file via Graph.from_osm(path), create agents with any policy class (Agent(policy=MyPolicy)), place them on start nodes (sim.add_agent(agent, node_id)), and launch the simulation with sim.run(steps=1000). Visualization is invoked with a single call sim.visualize(), which renders node/edge states, agent trajectories, and dynamic attributes such as traffic light phases. The framework also provides a recording module that emits a compressed representation of the entire state sequence, enabling efficient replay and offline analysis.

Experimental evaluation focuses on two large‑scale case studies: (a) Manhattan’s road network (≈ 2,800 traffic signals) and (b) a synthetic communication network with 5,000 nodes. In both scenarios, GAMMS maintains an average step time under 30 ms and memory consumption below 1 GB on a standard laptop (Intel i7, 16 GB RAM). The authors benchmark three distinct policy families—(i) a large language model (LLM) that generates high‑level waypoints, (ii) a reinforcement‑learning agent trained on a graph‑based navigation task, and (iii) a classic Dijkstra/A* planner. Results show comparable path optimality across policies while highlighting differences in collision avoidance and adaptability to dynamic edge weights (e.g., changing traffic signal timings). Importantly, the same simulation environment and visualization pipeline were reused without code changes, demonstrating the claimed integration‑first advantage.

The paper concludes that GAMMS successfully delivers a scalable, user‑friendly, and extensible platform for multi‑agent research that is grounded in real‑world data yet remains lightweight enough for rapid prototyping. Future work includes adding true multi‑threaded and distributed execution, richer physics and sensor models for hybrid high‑/low‑fidelity simulations, and dedicated modules for LLM‑agent collaboration (e.g., prompting agents to negotiate routes in real time). The open‑source release (GitHub link provided) invites the community to extend the framework, fostering a more inclusive ecosystem for multi‑agent system development.