Integration of MATSim and Large Language Models: A New Paradigm for Intelligent Traffic Simulation

This article introduces the matsim_llm_plugins project, which develops LLM plugins for the MATSim multi-agent traffic simulation framework. It enables agent-level conversational decision-making, tool calling, and RAG enhancement, providing a new AI-driven approach for traffic behavior modeling.

Traffic system simulation has always been a core tool in urban planning and traffic engineering. MATSim (Multi-Agent Transport Simulation), as a leading multi-agent traffic simulation framework in the industry, can simulate the behavior of millions of travelers in complex road networks. However, traditional MATSim agent decision models are often based on fixed utility functions and rules, making it difficult to capture the complexity and adaptability in human travel behavior.

With the rapid development of large language models (LLMs), researchers have begun to explore integrating the cognitive capabilities of LLMs into the field of traffic simulation. The matsim_llm_plugins project is an innovative attempt born in this context; it develops a complete set of LLM integration plugins for the MATSim framework, enabling simulation agents to make human-like conversational decisions.

The matsim_llm_plugins project adopts a modular architecture design, with the core goal of establishing a bidirectional interaction channel between MATSim agents and LLMs. The entire system is built around several key components:

ChatManager: The Dialogue Hub for Agents

Each MATSim agent is equipped with an independent ChatManager instance, which is the foundation for realizing persistent memory and multi-turn reasoning. ChatManager maintains a complete dialogue history, is responsible for sending requests to LLMs, and handles multi-step tool execution processes. This design ensures that each simulation agent has an independent "thinking thread" and can make coherent decisions based on historical interactions.

Tool Calling Framework: From Language to Action

The project implements a complete tool calling mechanism, supporting two types of tools:

• LLM Tools: Execution results are returned to the LLM for further reasoning
• Dummy Tools: Execution results are directly consumed by MATSim to trigger simulation state changes

Tool parameters are defined via Java DTOs, which are automatically converted into JSON Schema visible to LLMs, enabling type-safe parameter passing and validation. The system supports parallel tool calls; LLMs can request the execution of multiple tools in a single response, and the system will iteratively execute them until all tools are completed.

Retrieval-Augmented Generation (RAG): Dynamic Context Injection

To enable LLMs to access real-time information from the simulation environment, the project integrates a RAG system based on vector databases:

• Static Context: Road network data, pricing information, infrastructure layout
• Dynamic Context: Agent historical experience, runtime state, environmental changes

Through the Qdrant vector database and LangChain4j framework, the system can retrieve relevant context in milliseconds, providing accurate background information for LLM decision-making.

Backend-Agnostic Architecture Design

The project adopts a backend-agnostic design philosophy, supporting multiple LLM service providers:

Backend Type	Access Method	Features
OpenAI	HTTPS API	Cloud service with complete functionality
LM Studio	Local OpenAI-compatible endpoint	Local deployment for privacy protection
Ollama	OpenAI-compatible mode	Open-source model with low cost

This flexibility allows researchers to choose the appropriate service backend according to scenario requirements, enabling seamless switching from experimental local deployments to production-level cloud services.

Deep Integration with MATSim

The project is deeply integrated with the MATSim core through the Guice dependency injection framework, providing three integration modes:

1. Replanning Mode: LLM planning based on strategies, called during the regular replanning phase
2. Within-day Mode: Real-time decision updates to respond to unexpected events during simulation
3. Controller Listener Mode: Global lifecycle integration, triggered at key simulation nodes

This layered integration strategy allows researchers to choose the appropriate depth of intervention based on research questions, from lightweight strategy generation to fully LLM-driven behavior modeling.

Data Generation and Fine-Tuning Support

The project has built-in JSONL logging functionality, which automatically captures the complete interaction history between agents and LLMs. This data can be used for:

• Fine-tuning: Optimizing LLM behavior based on actual simulation data
• Distillation: Training smaller, faster dedicated models
• Behavior Analysis: Understanding LLM decision patterns and verifying simulation rationality

New Dimensions in Behavior Modeling

Traditional traffic behavior models are limited by preset utility functions and finite variable dimensions. By introducing LLMs, researchers can:

• Simulate complex social-psychological factors such as habit formation, peer influence, and information acquisition behavior
• Implement natural language-based demand surveys, allowing agents to "describe" their travel preferences
• Study the acceptance dynamics of emerging travel services (e.g., autonomous driving, shared mobility)

Intelligent Policy Evaluation

In traffic policy evaluation scenarios, LLM-enhanced MATSim can:

• Simulate public reactions to new policies without expensive stated preference surveys
• Evaluate the effectiveness of information dissemination strategies, such as the adoption rate of congestion warnings and route suggestions
• Analyze the differential responses of different groups to policy changes

Multimodal Traffic System Simulation

Combining MATSim's multimodal capabilities, LLM agents can:

• Make complex mode choice decisions in travel chains
• Dynamically adjust travel plans based on real-time information
• Simulate interactions with other agents (human drivers, autonomous vehicles)

Current Limitations

Although matsim_llm_plugins provides powerful functions, it still faces some challenges:

• Computational Cost: LLM calls have significant latency and cost overhead compared to traditional rule engines
• Interpretability: The "black box" nature of LLMs reduces the interpretability of behavior modeling
• Consistency: Ensuring agents exhibit stable behavior patterns across different runs requires careful design

Future Development Directions

The project roadmap shows that the development team is exploring the following directions:

1. Dedicated Model Training: Training small traffic domain-specific LLMs based on MATSim simulation data
2. Multi-Agent Collaboration: Enabling direct communication and coordination between agents
3. Real-Time Simulation Optimization: Reducing LLM call latency through caching and batch processing

The matsim_llm_plugins project represents an important technological leap in the field of traffic simulation. By integrating the cognitive capabilities of large language models into the MATSim framework, it opens up new possibilities for traffic behavior modeling. Although this method is still in the early exploration stage, its potential—from more natural behavior modeling to intelligent policy evaluation—deserves continuous attention from the traffic research community.

For researchers who want to try this technology, the project provides complete documentation and example code, supporting various deployment scenarios from local experiments to large-scale simulations. With the continuous advancement of LLM technology and the continuous reduction of costs, we have reason to expect that agent-driven traffic simulation will become an important tool for future urban planning.