search

Emerge-Lab / gpudrive

GPU-acceleration of Nocturne via Madrona
MIT License
195 stars 17 forks source link

readme

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: ```bash 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: ```bash 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: ```bash 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`: ```bash conda env create -f environment.yml ``` Activate the environment: ```bash conda activate gpudrive ``` Run: ```bash 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:

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