GPC-Bench: Game-Theoretic Planning and Control Benchmark for Autonomous Driving

A Python-based simulation platform built on SUMO and TraCI for testing and evaluating game-theoretic planning-and-control agents in interactive autonomous-driving scenarios, with a focus on unsignalized intersection interactions.

---

🎯 Overview

GPC-Bench is a simulation test platform for evaluating autonomous driving strategies in interactive scenarios. The platform provides a realistic environment for:

• Autonomous Driving Research - Ego vehicle navigation through unsignalized intersections
• Game Theory Applications - Game-based policies using offline 4D strategy tables
• LLM-Based Policy Evaluation - Local ML models trained on LLM-generated data (no API calls)
• Comprehensive Benchmarking - Standardized safety and efficiency metrics collection

The platform is designed for strategy benchmarking, allowing researchers to plug in custom Ego strategies, configure NPC traffic density and behavior patterns, and collect standardized metrics for safety and efficiency analysis.

---

✨ Features

Ego Vehicle Policies

Policy	Description	Decision Logic
First-Come-First-Go	ETA-based priority policy	Uses Estimated Time of Arrival to determine priority at intersections
Game-Based	4D strategy table with multilinear interpolation	Queries pre-computed equilibrium strategy tables

NPC Traffic Policies

Policy	Description	Driving Styles
Rule-Based	Gap acceptance logic	Aggressive, Moderate, Conservative
Game-Based	4D strategy table policy	Aggressive, Moderate, Conservative
LLM-Based	Local ML models (no API calls)	OpenAI, DeepSeek, Doubao, Gemini

Platform Capabilities

• Configurable Traffic Flows - Four independent traffic flows (A, B, C, D) with customizable density
• Real-time Visualization - Optional PyQt5 dashboard with live plotting
• Comprehensive Metrics - Collision detection, distance tracking, timing analysis
• Extensive Logging - JSONL decisions, JSON summaries, and CSV exports
• Reproducible Experiments - Random seed support for consistent results

---

🔧 Installation

Prerequisites

• OS: Linux (tested on Ubuntu 20.04+)
• Python: 3.8 or later (3.10 recommended)
• SUMO: 1.24.0 or compatible

Step 1: Install SUMO

sudo apt-get update
sudo apt-get install sumo sumo-tools

For detailed SUMO installation instructions, visit https://www.eclipse.org/sumo/.

Step 2: Clone Repository

git clone https://github.com/yourusername/sumo_plat.git
cd sumo_plat

Step 3: Create Virtual Environment

Using venv:

python3 -m venv venv
source venv/bin/activate

Or using conda:

conda create -n sumo_sim python=3.10 -y
conda activate sumo_sim

Step 4: Install Dependencies

pip install -r requirements.txt

Step 5: Set Environment Variables

Add to ~/.bashrc or ~/.zshrc:

# Default SUMO installation path
export SUMO_HOME=/usr/share/sumo

# If SUMO is installed elsewhere, adjust the path:
# export SUMO_HOME=/path/to/your/sumo

export PATH=$SUMO_HOME/bin:$PATH
export PYTHONPATH=$SUMO_HOME/tools:$PYTHONPATH

Then source your shell configuration:

source ~/.bashrc   # or ~/.zshrc

Step 6: Verify Installation

# Check SUMO installation
which sumo sumo-gui

# Check Python TraCI module
python -c "import traci; print('TraCI OK')"

# Run tests
python -m unittest discover tests/ -v

---

🤖 Quick Start

Basic Usage

# Run with default settings (GUI enabled)
python main.py

# Run headless (no GUI)
python main.py --no-gui --no-dashboard

# Run with PyQt dashboard for real-time monitoring
python main.py --dashboard

Command-Line Options

Option	Default	Description
--config, -c	configs/default.yaml	Configuration file path
--seed, -s	None	Random seed for reproducibility
--output-dir, -o	logs	Output directory for logs
--gui	True	Enable SUMO GUI
--no-gui	-	Disable SUMO GUI (headless mode)
--dashboard	False	Enable PyQt dashboard
--npc-count	8	Vehicles per flow (A,B,C,D)
--npc-ratio	3:4:3	Aggressive:Moderate:Conservative ratio
--npc-policy	rule_based	NPC policy type
--llm-provider	deepseek	LLM provider for llm_based
--ego-policy	first_come_first_go	Ego policy type
--ego-style	moderate	Ego style for game_based

Usage Examples

# Ego: Game-based policy with moderate style
python main.py --ego-policy game_based --ego-style moderate --no-gui --no-dashboard

# NPC: Game-based policy
python main.py --npc-policy game_based --no-gui --no-dashboard

# NPC: LLM-based policy with OpenAI provider
python main.py --npc-policy llm_based --llm-provider openai --no-gui --no-dashboard

# Combine Ego game-based with NPC game-based
python main.py --ego-policy game_based --ego-style aggressive --npc-policy game_based --no-gui --no-dashboard

# Reproducible experiment with fixed seed
python main.py --seed 42 --npc-count 10 --no-gui --no-dashboard

---

📊 Documentation

Policy Configuration

Ego Policies

First-Come-First-Go (first_come_first_go)

Uses Estimated Time of Arrival (ETA) to determine priority at intersections. The Ego vehicle yields to vehicles with earlier ETAs.

policy_params:
  fcfg:
    junction_influence_radius: 50.0  # Distance from junction to activate (m)
    eta_epsilon: 0.5                  # ETA comparison threshold (s)
    safety_gap: 2.0                   # Minimum safety gap (s)
    yield_decel: 3.0                  # Yielding deceleration (m/s²)

Game-Based (game_based)

Uses offline 4D strategy tables with multilinear interpolation.

• Input: [d1, v1, d2, v2] → Output: acceleration
  • d1: Ego distance to conflict point (m)
  • v1: Ego speed (m/s)
  • d2: Opponent distance to conflict point (m)
  • v2: Opponent speed (m/s)
• Decision rate: 2 Hz (every 0.5s)
• Interaction zone: 50m before junction

Style	Behavior	Strategy Table
Aggressive	Risk-taking	strategy_table_aggressive.npz
Moderate	Balanced	strategy_table_moderate.npz
Conservative	Cautious	strategy_table_conservative.npz

NPC Policies

Rule-Based (rule_based)

Uses gap acceptance logic.

Style	Gap Acceptance	Speed Factor
Aggressive	1.5s	1.2x
Moderate	2.5s	1.0x
Conservative	4.0s	0.8x

LLM-Based (llm_based)

Uses local ML models trained on LLM-generated data. No API calls are made during simulation.

policies/LLM/
├── openai/
│   ├── model.pkl
│   ├── scaler.pkl
│   └── metadata.json
├── deepseek/
│   ├── model.pkl
│   ├── scaler.pkl
│   └── metadata.json
└── ...

Custom Policy Implementation

To add a custom Ego strategy:

1. Create a new policy file:

# policies/my_custom_policy.py
from policies.base import EgoPolicyBase, Observation, Action

class MyCustomPolicy(EgoPolicyBase):
    def __init__(self, params=None):
        super().__init__(name="my_custom", params=params)

    def decide(self, obs: Observation) -> Action:
        # Implement your decision logic here
        return Action(
            target_speed=15.0,
            acceleration=0.0,
            rationale="Your decision explanation"
        )

2. Export in policies/__init__.py:

from .my_custom_policy import MyCustomPolicy

3. Register in main.py (add to the create_policies function):

if ego_policy_name == "my_custom":
    ego_policy = MyCustomPolicy(params=ego_params)

4. Run via CLI:

python main.py --ego-policy my_custom --no-gui --no-dashboard

Policy Interface Contract

All Ego policies must inherit from EgoPolicyBase and implement:

class EgoPolicyBase:
    def reset(self) -> None:
        """Reset policy state between simulation runs."""

    def decide(self, obs: Observation) -> Action:
        """Generate action for current timestep.

        Args:
            obs: Observation containing ego state, surrounding vehicles,
                 target junction, junction position, etc.

        Returns:
            Action with target_speed (m/s), acceleration (m/s²),
            and rationale (description string).
        """

---

Project Structure

sumo_plat/
├── configs/                         # Configuration files
│   └── default.yaml                 # Main configuration
├── gui/                             # Visualization components
│   ├── dashboard.py                 # PyQt5 real-time dashboard
│   └── __init__.py
├── networks/                        # SUMO network files
│   ├── interactive_scenario.net.xml # Road network definition
│   ├── interactive_scenario.rou.xml # Vehicle routes (auto-generated)
│   └── gui_settings.xml             # SUMO GUI settings
├── policies/                        # Decision policies
│   ├── __init__.py
│   ├── base.py                      # Base policy classes
│   ├── ego_first_come_first_go.py   # Ego FCFG policy
│   ├── ego_game_based.py            # Ego game-based policy
│   ├── npc_rule_based.py            # NPC rule-based policy
│   ├── npc_game_based.py            # NPC game-based policy
│   ├── npc_llm_based.py             # NPC LLM-based policy
│   └── LLM/                         # LLM provider models
├── scripts/                         # Utility scripts
│   ├── run_gui.sh
│   └── run_headless.sh
├── sim/                             # Core simulation components
│   ├── __init__.py
│   ├── logger.py                    # Logging utilities
│   ├── metrics.py                   # Metrics computation
│   ├── observation_builder.py       # Observation construction
│   ├── route_generator.py           # Route generation
│   ├── state_extractor.py           # State extraction from SUMO
│   └── sumo_runner.py               # TraCI simulation manager
├── main.py                          # Main entry point
├── requirements.txt                 # Python dependencies
├── LICENSE                          # MIT License
├── README.md                        # This file
└── README_zh.md                     # 中文文档

---

🔧 Outputs & Logging

Simulation results are saved to timestamped directories:

logs/run_YYYYMMDD_HHMMSS/
├── decisions.jsonl      # Per-decision logs (one JSON per line)
├── steps.jsonl          # Per-step metrics
├── summary.json         # Final summary with all metrics
└── metrics.csv          # CSV for data analysis

Key Metrics

Metric	Description
collision_count	Number of collisions detected
collision_occurred	Boolean indicating if any collision occurred
min_distance	Minimum distance between any vehicles (m)
avg_min_distance	Average minimum distance across all vehicles (m)
avg_speed	Average speed (m/s)
yield_count	Number of yield decisions
decision_count	Total decisions made
yield_rate	Ratio of yield to total decisions
duration	Simulation duration (s)
ego_finished	Whether ego vehicle completed route

---

↻ Reproducibility

Setting Random Seeds

# Set seed for reproducible results
python main.py --s