README.md

Multi-Agent Traffic Scenario Gym

MATS-Gym is a PettingZoo environment for training and evaluating autonomous driving agents in CARLA. Environments can be created from scenarios that are implemented as ScenarioRunner scenarios, allowing to leverage a large number of existing driving scenarios. Furthermore, we provide an integration with Scenic which allows us to sample scenarios from Scenic specifications.

Main Features

• Supports multiple scenario specification standards:
  • Scenic
  • OpenSCENARIO
  • ScenarioRunner
  • Full compatibility with CARLA Challenge scenarios
• Multi-Agent environment
• Determinism and reproducibility (via replay functionality)
• Various types of observations:
  • Birdview
  • Sensor data (e.g. RGB camera, depth camera, lidar)
  • Map data (e.g. lane centerlines, lane boundaries, traffic lights)
• Action spaces:
  • High level meta-actions (e.g. turn left, turn right, go straight, change lane)
  • Low level continuous control (throttle, brake, steer)

Installation

For now, you need to install the package from source. We recommend using a virtual environment.

To install the package, run the following command:

pip install git+https://github.com/AutonomousDrivingExaminer/mats-gym

Usage

Overview

The main idea of Scenario Gym is to run scenarios that are implemented as subclasses of BasicScenario, from the ScenarioRunner package. The main class, BaseScenarioEnv, handles most of the logic for running scenarios and controlling the agents. Furthermore, we provide adapters that handle sampling and initialization of scenarios from configuration or scenario files:

• ScenicEnv: samples scenes from Scenic scenarios and initializes ScenicScenario instances.
• ScenarioRunnerEnv: creates scenarios from scenario_runner configurations.

Examples

First, make sure that CARLA is running (if you have docker installed, you can use ./scripts/start-carla.sh to run it).

The following code snippet, shows you how to use a scenic scenario to create an environment instance:

import gymnasium
import mats_gym
from mats_gym.envs import renderers


env = mats_gym.scenic_env(
  host="localhost",  # The host to connect to
  port=2000,  # The port to connect to
  scenario_specification="scenarios/scenic/carla_challenge_08.scenic",
  scenes_per_scenario=5,  # How many scenes should be generated per scenario
  agent_name_prefixes=["sut", "adv"], # Each actor whose role-name starts with one of the prefixes is an agent.
  render_mode="human",  # The render mode. Can be "human" or "rgb_array".
  render_config=renderers.camera_pov(agent="sut"),
)

obs, info = env.reset()
terminated = False
while not terminated:
  action = {agent: ... for agent in env.agents}
  obs, reward, terminated, truncated, info = env.step(action)
...
env.close()

For more examples, have a look at the examples directory.