Platooning & Traffic Coordination Simulator for Research and Education

Overview

This repository contains:

1. The toolbox (Python package in /toolbox) with modular road segments, vehicle dynamics/controllers, perception, and visualization.
2. Several runnable simulation examples (e.g., similation_projects/project_1/Example_1), each with its own configuration.

The code is designed to be relatively easy to extend for future master students and researchers. Major design goals: modularity, reproducibility, and plug-and-play controllers/dynamics.

Citation

If you find the toolbox useful, please cite it as

Jamsahar, Wiltz, Charitidou, Dimarogonas: "A Modular Platooning and Vehicle Coordination Simulator for Research and Education". 2026.

Repository Structure

• toolbox/ Python package with the core simulator modules.
  • config/ Constants, enums, global tunables.
  • core/ Main simulation loop and API (SimulationProject, Traffic_Environment)
  • roads/ Road segment classes (Straight, Curved, Intersection) and relevant road segment modules.
  • segment_management/ SegmentConnectionManager + connectors and network updating.
  • vehicles/ Vehicle, dynamics, controllers, sensors & perception services.
  • visualization/ Pygame + Cairo-based drawing routines and utilities.
  • utils/ Geometry, frames, math helpers, small utilities.
• simulation_projects/ Project examples, logs, plots and videos
• README.txt This file: code structure + getting started + how to run examples.
• requirements.txt Python dependencies.
• docs/
  • FURTHER_DEVELOPMENT.txt Current issues and partially implemented features (with pointers to affected modules).

Python & OS Requirements

• Python 3.10+ recommended.
• Tested on Windows.
• Download the required packages. This will be shown in the Installation process.

Installation

To install the required packages do the following:

1. Create and activate a virtual environment (recommended):

   Windows (PowerShell): python -m venv .venv venv\Scripts\Activate.ps1

   Linux/macOS (bash/zsh): python3 -m venv .venv source .venv/bin/activate

2. Install dependencies:

   pip install -r requirements.txt

Getting Started (Run Examples)

The simulation_projects have the following structure and contain:

• simulation_projects/
  • project_1/ Self-contained example folders.
    • Example_1.json.gz Stored scenario
  • outputs/
    • logs/
      • vehicle_data_log.csv
    • plots/
      • vehicle_1_control_input.png (depends on configuration)
    • videos/
      • simulation_1.mp4

Step 1: Select the simulation project Open: toolbox/config/config.py

Set: SIMULATION_ID = 1 Loads project_1 -> Example_1 LOAD_PROJECT = True Runs the loaded scenario

Step 2: Run the simulator In the windows powershell or similar write the following from the repository root:

• cd platooning_simulator/toolbox
• python main.py

Step 3: View results Inside: simulation_projects/project_1/outputs/

You will find: logs/

• vehicle_data_log.csv

plots/

• vehicle_1_control_input.png
• vehicle_2_control_input.png
• ...

videos/

• simulation_1.mp4

To control what is logged or plotted, modify:

• toolbox/config/config.py
• toolbox/config/vehicle_data_logging.py

All configuration options are documented in comments in these files.

Extended Documentation

For a complete documentation of the toolbox, please refer to

Jamsahar, Kevin: "Design of a Modular Platooning and Traffic Coordination Simulator". Master Thesis, KTH Royal Institute of Technology, Stockholm (Sweden), 2025. Online available: https://urn.kb.se/resolve?urn=urn:nbn:se:kth:diva-377037

Where to Add New Features

• New road segment type -> toolbox/roads/
• New controller/dynamics -> toolbox/vehicles/
• New visualization backend -> toolbox/visualization/
• New utilities -> toolbox/utils/