Metadata-Version: 2.4
Name: pgtg
Version: 0.6.0
Summary: Python simulation of a driving challenge. Compatible with the Gymnasium API standard.
License-Expression: MIT
License-File: LICENSE
Author: Joshua Meyer
Author-email: joshua.meyer@cs.uni-saarland.de
Maintainer: Joshua Meyer
Maintainer-email: joshua.meyer@cs.uni-saarland.de
Requires-Python: >=3.11,<3.14
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Provides-Extra: all
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: examples
Requires-Dist: Pillow (>=9.0.0)
Requires-Dist: gymnasium (>=0.26.0)
Requires-Dist: marimo ; extra == "dev"
Requires-Dist: marimo ; extra == "examples"
Requires-Dist: matplotlib (>=3.4.0)
Requires-Dist: mkdocs-glightbox (>=0.4) ; extra == "docs"
Requires-Dist: mkdocs-material (>=9.5) ; extra == "docs"
Requires-Dist: mkdocstrings[python] (>=0.25) ; extra == "docs"
Requires-Dist: numpy (>=1.21.0)
Requires-Dist: pgtg[dev,docs,examples] ; extra == "all"
Requires-Dist: pre-commit (>=3.5.0) ; extra == "dev"
Requires-Dist: pydantic (>=2.1.0)
Requires-Dist: pydsmc (>=0.3.9) ; extra == "examples"
Requires-Dist: pygame (>=2.1.0)
Requires-Dist: pytest (>=7.0) ; extra == "dev"
Requires-Dist: pyyaml (>=6.0)
Requires-Dist: ruff (>=0.15,<0.16) ; extra == "dev"
Requires-Dist: ruff (>=0.15,<0.16) ; extra == "docs"
Requires-Dist: stable-baselines3 (>=2.5.0) ; extra == "examples"
Requires-Dist: torch ; extra == "examples"
Project-URL: Issues, https://github.com/neuro-mechanistic-modeling/pgtg/issues
Project-URL: Repository, https://github.com/neuro-mechanistic-modeling/pgtg
Description-Content-Type: text/markdown

# ProcGrid Traffic Gym (PGTG)

[![PyPI](https://img.shields.io/pypi/v/pgtg)](https://pypi.org/project/pgtg/)
[![Tests](https://github.com/neuro-mechanistic-modeling/pgtg/actions/workflows/tests.yml/badge.svg)](tests)
[![Docs](https://github.com/neuro-mechanistic-modeling/pgtg/actions/workflows/docs.yml/badge.svg)](https://neuro-mechanistic-modeling.github.io/pgtg/)
[![License](https://img.shields.io/github/license/neuro-mechanistic-modeling/pgtg)](LICENSE)

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](https://gymnasium.farama.org/).

## Getting Started

### Installation

**Requires Python 3.11, 3.12, or 3.13.**
PGTG is available on [PyPi](https://pypi.org/project/pgtg/) and can be installed with all major package managers:

```bash
pip install pgtg
```

For development from source, the repository uses [mise](https://mise.jdx.dev/) and
[uv](https://docs.astral.sh/uv/):

```bash
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:

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

### Usage

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

```python
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:

```python
from pgtg import PGTGEnv

env = PGTGEnv()
```

### Examples

The [`examples/`](examples/) directory ships runnable [marimo](https://marimo.io/)
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:

```bash
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`](examples/README.md) for the full list.

## Documentation

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

1. [Getting Started](https://neuro-mechanistic-modeling.github.io/pgtg/getting-started/installation/)
2. [Configuration Reference](https://neuro-mechanistic-modeling.github.io/pgtg/customization/configuration/)
3. [Extending PGTG](https://neuro-mechanistic-modeling.github.io/pgtg/extending/custom-obstacles/)

## Citation

If you use PGTG in your research, please cite the accompanying paper (RLC 2026); see the [Citation](https://neuro-mechanistic-modeling.github.io/pgtg/citation/):

```bibtex
@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},
}
```

