ProcGrid Traffic Gym (PGTG)

Procedurally Generated Grid-Based Traffic Gym (PGTG), a feature-rich, extensible, and customizable reinforcement learning benchmark. PGTG requires an agent to navigate procedurally generated tracks while having to manage momentum and being exposed to various stochastic obstacles and the unpredictable behaviour of traffic participants. It provides fine-grained control over the map generation, traffic rules, obstacles, and the observation and reward functions. It is fully compatible with the Gymnasium API standard.

Getting Started

Installation

Requires Python 3.11, 3.12, or 3.13. PGTG is available on PyPi and can be installed with all major package managers:

pip install pgtg

For development from source, the repository uses mise and uv:

mise run install # create the .venv and install ".[all]"
mise run test    # run the test suite
mise run docs    # build the docs (add --serve for live preview)

Or manually with uv/pip:

uv venv && uv pip install -e ".[all]"

Usage

The easiest way to use PGTG is to create the environment with gymnasium:

import gymnasium as gym

env = gym.make("pgtg-v5")

The package relies on import side-effects to register the environment name so, even though the package is never explicitly used, its import is necessary to access the environment.

The environment constructor can also be used directly:

from pgtg import PGTGEnv

env = PGTGEnv()

Examples

The examples/ directory ships runnable marimo notebooks — an interactive playground, two Stable-Baselines3 training scripts (MLP and a custom CNN feature extractor), and a statistical evaluation with PyDSMC. Each is both a notebook and a CLI script and needs no setup:

uvx marimo edit --sandbox examples/explore_pgtg.py # click around
uv run --script examples/train_mlp_sb3.py          # train an agent

See examples/README.md for the full list.

Documentation

Full documentation is available at https://neuro-mechanistic-modeling.github.io/pgtg/:

1. Getting Started
2. Configuration Reference
3. Extending PGTG

Citation

If you use PGTG in your research, please cite the accompanying paper (RLC 2026); see the Citation:

@article{meyer2026pgtg,
  title   = {{PGTG}: Procedurally Generated Grid-Based Traffic Gym},
  author  = {Meyer, Joshua and Kuntz, Felix M. and Wolf, Verena and
             Hoffmann, J{\"o}rg and Gros, Timo P.},
  journal = {Reinforcement Learning Journal},
  year    = {2026},
}