An agent-based traffic simulation built using the autogen framework, for visualizing the interaction between vehicles, traffic lights, pedestrian crossings, and parking areas. The simulation is organized around a message-passing architecture, where each element (vehicle, traffic light, pedestrian crossing, parking area) runs as an independent agent with its own logic.

• Daniel Molina Pinel (50%): Focused on agents and worked on environment
• Mehmet Batuhan Duman (50%): Focused on environment and worked on agents.

1. Features
2. Getting Started
3. Simulation Modes
4. Configuration & Map Editing
5. Parking System
6. Implementation Details
7. File-by-File Overview
   • base.py
   • parking.py
   • pedestrian.py
   • traffic_light.py
   • rl/traffic_lihgt.py (RL model)
   • rl/parking.py (RL model)
   • rl/pedestrian.py (RL model)
   • vehicle.py
   • main.py
   • runtime.py
   • simui.py
8. Reinforcement Learning
9. Future Improvements
10. Simulation Input Parameters
11. Troubleshooting

• Agent-Based Architecture: Built using the autogen framework, each simulation element (vehicle, light, crossing, parking) is an autonomous agent communicating via asynchronous messages.
• Asynchronous Simulation: All agents operate and update their states concurrently.
• Interactive Visualization: Real-time Tkinter GUI (vis/simui.py) displays the map, agents, and their states (colors, text labels). Supports panning and zooming.
• Configurable Map & Parameters:
  • Define map layout (roads, intersections, agent placement) via JSON files (map_config.json, basic_map_config.json).
  • Override simulation parameters (timings, capacities, RL settings) via command-line arguments (see Simulation Input Parameters).
• Road Network:
  • Supports configurable road segments with capacity limits, one-way streets, and explicit connections.
  • Includes vehicle spawn and despawn points defined in the map configuration.
• Vehicle Behavior:
  • Vehicles navigate roads based on connections, attempt turns at intersections, and follow routes.
  • Respect traffic signals (lights, crossings) and road capacity, waiting when necessary.
  • Basic collision avoidance logic (primarily by checking obstacles ahead and road capacity).
• Traffic Lights:
  • Standard mode: Lights operate in coordinated groups (N/S vs E/W) on fixed timers.
  • RL mode (--use-rl): Optional TrafficLightRLAssistant agents use Q-learning (rl/traffic_lihgt.py) to dynamically adjust signals based on simulated queue lengths.
• Pedestrian Crossings:
  • Standard mode: Simulate pedestrian arrivals and occupy the crossing for a fixed or random duration.
  • RL mode (--use-rl): Optional PedestrianCrossingRLAssistant agents use Q-learning (rl/pedestrian.py) to decide when to allow crossings based on pedestrian queue length and road type.
• Parking System (complete mode only):
  • Supports different parking area types (“street”, “roadside”, “building”) with configurable capacity, parking time, and exit time.
  • Vehicles can find nearby parking, request entry, park for a duration, and exit.
  • Standard mode: Parking areas manage occupancy and timed exits.
  • RL mode (--use-rl): Optional ParkingRLAssistant agents use Q-learning (rl/parking.py) to learn optimal exit strategies based on occupancy and duration.
• Simulation Modes: Easily switch between basic (no parking) and complete (with parking) modes via command-line argument.
• Logging: Key simulation events, agent actions, and final statistics are logged to a timestamped file in the LOGS/ directory.

• Python 3.7+ (Developed and tested with Python 3.11)

It’s recommended to use a virtual environment to manage dependencies.

# Navigate to the project directory
cd path/to/traffic_agents

# Create a virtual environment (if 'myenv' doesn't exist)
python -m venv myenv # Uncomment if needed

# Activate the virtual environment
# On Windows 
.myenvScriptsactivate
# On macOS/Linux
source myenv/bin/activate

Make sure your virtual environment is activated, then install the required libraries:

pip install -r requirements.txt

There are two primary modes:

python main.py basic [OPTIONS]

Example: python main.py basic --sim-time 60

This launches a simplified simulation without parking areas, focusing only on vehicles, traffic lights, and pedestrian crossings. It reads basic_map_config.json for the map layout.

python main.py complete [OPTIONS]
# Or simply (defaults to complete mode):
python main.py [OPTIONS]

Example: python main.py --sim-time 120 --use-rl

This launches the full simulation with all features, including parking and Reinforcement Learning. It reads map_config.json by default. A Tkinter window will appear, showing the simulation in real-time.

See Simulation Input Parameters for available [OPTIONS].

1. Basic Mode (basic)

   • Uses basic_map_config.json
   • Focuses on traffic flow, traffic lights, and pedestrian crossings
   • Vehicles navigate intersections, avoid collisions, and obey signals
   • Ideal for studying fundamental traffic movement without parking

2. Complete Mode (complete)

   • Uses map_config.json (default if no mode is specified)
   • Includes all basic features plus parking areas
   • Vehicles may park, exit parking after some time, or skip parking if full
   • Parking areas have capacities, parking/exit times, and occupancy indicators
   • Shows the synergy between road traffic flow and parking availability

The simulation reads from JSON configuration files (map_config.json or basic_map_config.json) to define:

• Vehicles: Initial state and properties.
• Traffic Lights: Location and type (standard/RL).
• Pedestrian Crossings: Location and type (standard/RL).
• Parking Areas: Location, capacity, type, timings.
• Roads: Geometry, connections, capacity, and other properties.

A typical map_config.json structure:

{
  "vehicles": [
    { "id": "vehicle_1", "x": 100, "y": 400, "spawn": true }
  ],
  "traffic_lights": [
    { "id": "traffic_light_1", "x": 100, "y": 0 }
  ],
  "crossings": [
    { "id": "crossing_1", "x": 100, "y": 100 }
  ],
  "parking_areas": [
    {
      "id": "street_parking_1",
      "x": 150,
      "y": 50,
      "capacity": 3,
      "parking_time": 2,
      "exit_time": 1,
      "type": "street"
    }
  ],
  "roads": [
    {
      "id": "road_0",
      "x1": 0,
      "y1": 100,
      "x2": 700,
      "y2": 100,
      "capacity": 2,
      "one_way": false,
      "is_spawn_point": true,
      "is_despawn_point": false
    }
  ]
}

1. Vehicles
   • Define starting locations (x, y) or use spawn: true to use defined spawn_points in the map config.
2. Traffic Lights
   • Control traffic flow at intersections (either timed or RL-based).
3. Pedestrian Crossings
   • Occupy roads when pedestrians are crossing; vehicles must wait. Can be standard or RL-based.
4. Parking Areas
   • Define capacity, parking_time, exit_time, and type (“street”, “roadside”, or “building”).
5. Roads
   • Each road has start/end coordinates (x1, y1, x2, y2), a unique id, and optional properties like capacity, one_way (boolean), is_spawn_point (boolean), is_despawn_point (boolean), and connections (list of road IDs this road leads to).

The simulation provides a flexible parking system where vehicles can decide to park if they find an available spot:

• Street Parking: Smaller capacity, faster parking/exit times.
• Parking Buildings: Larger capacity, potentially slower times for parking/exit.

1. Driving – Default state while on the road.
2. Parking – Currently transitioning into a parking area (takes parking_time seconds).
3. Parked – Vehicle is stationary in the lot.
4. Exiting – Transitioning out of the parking area (takes exit_time seconds).
5. Searching – Checking if a parking area has capacity or deciding whether to park.

The parking areas visually change color based on occupancy (blue/orange/red) and display (current occupancy / capacity) to indicate how many vehicles are parked.

• All simulation elements extend a base class MyAssistant (in base.py).
• Agents handle messages asynchronously with the @message_handler decorator.
• Example: A ParkingAssistant might receive a “park_vehicle” message from a vehicle and update its occupancy.

• Vehicles track their progress along roads, and can wait if another vehicle is too close or if a traffic light is red.
• Lane capacity is respected, so if the capacity is reached, incoming vehicles may slow or queue.

• Built with Tkinter (simui.py).
• Each agent (vehicle, crossing, etc.) has a corresponding “visual object” in the UI, drawn on a canvas with shapes, colors, and text labels.
• The UI also includes side panels displaying agent info (like vehicle status, parking occupancy, etc.).

• Vehicle Color: Indicates the vehicle’s current state:
  • Green: Parked.
  • Blue: Parking or Exiting parking.
  • Orange: Has experienced wait times (Orange = longer waits).
  • Default Blue: Driving normally, no significant waits.
  • Gray: Default/fallback color.
• Percentage: Shown next to the vehicle ID (Vehicle1 (75%)), this indicates the vehicle’s progress along its current road segment (0% = start, 100% = end). Only shown when driving.

• Defines MyAssistant, an abstract base agent class.
• Implements handle_my_message_type as a default message handler.
• Provides common placeholders for road property processing.

• ParkingAssistant manages a parking area:
  • Tracks capacity, vehicles in parking, exit timers, etc.
  • Runs a background coroutine (run_parking_area) that updates parking states every second.
  • Responds to messages for parking requests, state queries, and exit notifications.
• ParkingRLAssistant uses reinforcement learning (rl.parking.ParkingRL) to decide when vehicles should exit, aiming to optimize space usage.

• Contains:
  1. PedestrianCrossingAssistant – Standard, rule-based pedestr