From 7be86a55f0c34ef64008eb1da79a0371784d25af Mon Sep 17 00:00:00 2001 From: Quentin18 Date: Mon, 21 Oct 2024 22:11:05 +0200 Subject: [PATCH] docs: add project description in readme --- README.md | 168 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 166 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a609c17..4370c12 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,166 @@ -# gymnasium-search-race -Gymnasium environment for the Search Race CG puzzle +# Gymnasium Search Race + +[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/) +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) +[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/) + +Gymnasium environment for +the [Search Race CodinGame optimization puzzle](https://www.codingame.com/multiplayer/optimization/search-race). + + + + + + + + + + + + + + + + +
Action SpaceBox([-1, 0], [1, 1], float64)
Observation SpaceBox([0, 0, 0, 0, 0, 0, -1, -1, 0], [1, 1, 1, 1, 1, 1, 1, 1, 1], float64)
importgymnasium.make("gymnasium_search_race:gymnasium_search_race/SearchRace-v0")
+ +## Installation + +To install `gymnasium-search-race` with pip, execute: + +```bash +pip install gymnasium_search_race +``` + +From source: + +```bash +git clone https://github.com/Quentin18/gymnasium-search-race +cd gymnasium-search-race/ +pip install -e . +``` + +## Environment + +### Action Space + +The action is a `ndarray` with 2 continuous variables: + +- The rotation angle between -18 and 18 degrees, normalized between -1 and 1. +- The thrust between 0 and 200, normalized between 0 and 1. + +### Observation Space + +The observation is a `ndarray` of 9 continuous variables: + +- The x and y coordinates of the next checkpoint. +- The x and y coordinates of the checkpoint after next checkpoint. +- The x and y coordinates of the car. +- The horizontal speed vx and vertical speed vy of the car. +- The facing angle of the car. + +The values are normalized between 0 and 1, or -1 and 1 if negative values are allowed. + +### Reward + +The goal is to visit all checkpoints as quickly as possible, as such the agent is penalised with a reward of `-0.1` for +each timestep. +When a checkpoint is visited, the agent is awarded with a reward of `1000/total_checkpoints`. + +### Starting State + +The starting state is generated by choosing a random CodinGame test case. + +### Episode End + +The episode ends if either of the following happens: + +1. Termination: The car visit all checkpoints before the time is out. +2. Truncation: Episode length is greater than 600. + +### Arguments + +- `test_id`: test case id to generate the checkpoints (see + choices [here](https://github.com/Quentin18/gymnasium-search-race/tree/main/src/gymnasium_search_race/envs/maps)). The + default value is `None` which selects a test case randomly when the `reset` method is called. + +```python +import gymnasium as gym + +gym.make("gymnasium_search_race:gymnasium_search_race/SearchRace-v0", test_id=1) +``` + +## Usage + +You can use [RL Baselines3 Zoo](https://github.com/DLR-RM/rl-baselines3-zoo) to train and evaluate agents: + +```bash +pip install rl_zoo3 +``` + +### Train an Agent + +The hyperparameters are defined in `hyperparams/ppo.yml`. + +To train a PPO agent for the Search Race game, execute: + +```bash +python -m rl_zoo3.train \ + --algo ppo \ + --env gymnasium_search_race/SearchRace-v0 \ + --tensorboard-log logs \ + --eval-freq 10000 \ + --eval-episodes 10 \ + --gym-packages gymnasium_search_race \ + --conf-file hyperparams/ppo.yml \ + --progress +``` + +### Enjoy a Trained Agent + +To see a trained agent in action on random test cases, execute: + +```bash +python -m rl_zoo3.enjoy \ + --algo ppo \ + --env gymnasium_search_race/SearchRace-v0 \ + --n-timesteps 10000 \ + --deterministic \ + --gym-packages gymnasium_search_race \ + --load-best \ + --progress +``` + +## Tests + +To run tests, execute: + +```bash +pytest +``` + +## Citing + +To cite the repository in publications: + +```bibtex +@misc{gymnasium-search-race, + author = {Quentin Deschamps}, + title = {Gymnasium Search Race}, + year = {2024}, + publisher = {GitHub}, + journal = {GitHub repository}, + howpublished = {\url{https://github.com/Quentin18/gymnasium-search-race}}, +} +``` + +## References + +- [Gymnasium](https://github.com/Farama-Foundation/Gymnasium) +- [RL Baselines3 Zoo](https://github.com/DLR-RM/rl-baselines3-zoo) +- [Stable Baselines3](https://github.com/DLR-RM/stable-baselines3) +- [CGSearchRace](https://github.com/Illedan/CGSearchRace) + +## Author + +[Quentin Deschamps](mailto:quentindeschamps18@gmail.com)