/gpudrive

GPU-acceleration of Nocturne via Madrona

Primary LanguageJupyter NotebookMIT LicenseMIT

GPUDrive

Python version Poetry Paper

GPUDrive is a GPU-accelerated, multi-agent driving simulator that runs at 1 million FPS. The simulator is written in C++, built on top of the Madrona Game Engine. We provide Python bindings and gymnasium wrappers in torch and jax, allowing you to interface with the simulator in Python using your preferred framework.

For more details, see our paper 📜 and the 👉 introduction tutorials, which guide you through the basic usage.

...

Agents in GPUDrive can be controlled by any user-specified actor.

Implemented algorithms 🌱

Algorithm Reference README
IPPO Paper Source

Installation 🛠️

To build GPUDrive, ensure you have all the dependencies listed here. Briefly, you'll need a recent version of Python and CMake (>= version 3.22), as well as Xcode on macOS or Visual Studio on Windows.

Once you have the required dependencies, clone the repository (don't forget --recursive!):

git clone --recursive https://github.com/Emerge-Lab/gpudrive.git
cd gpudrive
Optional: If you want to use the Madrona viewer in C++ (Not needed to render with pygame)

Extra dependencies to use Madrona viewer

To build the simulator with visualization support on Linux (build/viewer), you will need to install X11 and OpenGL development libraries. Equivalent dependencies are already installed by Xcode on macOS. For example, on Ubuntu:

  sudo apt install libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev mesa-common-dev libc++1

Then, you can choose between two options for building the simulator:

Option 1️⃣ : Manual install

For Linux and macOS, use the following commands:

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j # cores to build with, e.g. 32
cd ..

For Windows, open the cloned repository in Visual Studio and build the project using the integrated cmake functionality.

Next, set up the Python components of the repository with pip:

pip install -e . # Add -Cpackages.madrona_escape_room.ext-out-dir=PATH_TO_YOUR_BUILD_DIR on Windows
Option 2️⃣ : Poetry install

First create a conda environment using environment.yml:

conda env create -f environment.yml

Activate the environment:

conda activate gpudrive

Run:

poetry install

Test whether the installation was successful by importing the simulator:

import gpudrive

Getting started 🚀

To get started, see our intro tutorials. These tutorials take approximately 30-60 minutes to complete and will guide you through the dataset, simulator, and how to populate the simulator with different types of actors.

Tests 📈

To further test the setup, you can run the pytests in the root directory:

pytest

To test if the simulator compiled correctly (and python lib did not), try running the headless program from the build directory.

cd build
./headless CPU 1 # Run on CPU, 1 step

Dataset { 🚦 🚗 🚙 🛣️ }

How to download the Waymo Open Motion Dataset

Two versions of the dataset are available:

  • a mini-one that is about 1 GB and consists of 1000 training files and 100 validation / test files at: Dropbox Link.
  • the full dataset (150 GB) and consists of 134453 training files and 12205 validation / test files: Dropbox Link

The simulator supports initializing scenes from the Nocturne dataset. The input parameter for the simulator json_path takes in a path to a directory containing the files in the Nocturne format. The SceneConfig dataclass in pygpudrive/env/config.py dataclass is used to configure how scenes are selected from a folder with traffic scenarios.

Citations

If you use GPUDrive in your work, please cite us:

@misc{kazemkhani2024gpudrivedatadrivenmultiagentdriving,
      title={GPUDrive: Data-driven, multi-agent driving simulation at 1 million FPS},
      author={Saman Kazemkhani and Aarav Pandya and Daphne Cornelisse and Brennan Shacklett and Eugene Vinitsky},
      year={2024},
      eprint={2408.01584},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2408.01584},
}

Contributing and learning benchmark 👷‍♀️

If you find a bug of are missing features, please feel free to create an issue or start contributing! That link also points to a learning benchmark complete with training logs and videos of agent behaviors via wandb.

Timeline

GPUDrive