Cleaning Robots Gym

Gymnasium-compatible reinforcement-learning environment for the cleaning-robot MDP described in the paper preprint.

Developed by the IROS Lab team, Faculty of Computer Science (Fasilkom), Universitas Indonesia. Current planned package version: 0.1.0a1 (alpha).

Installation

pip install -e .
pip install -e ".[research]"

These commands install from this checkout. Once an alpha release is published, install that exact release with pip install cleaning-robots-gym==0.1.0a1.

The first command installs the environment. The second adds training, plotting, rendering, and video dependencies. For video only, use pip install -e ".[video]".

Repository Structure

cleaning-robots-gym/
|-- cleaning_robots_gym/       # Installable environment package
|   |-- __init__.py           # Gymnasium registration and public imports
|   |-- envs/
|   |   `-- cleaning_robot_env.py
|   `-- config/
|       `-- cleaning_robots_v0.yaml
|-- scripts/                  # Training, evaluation, plotting, video
|-- docs/                     # Experiment documentation and figures
|   `-- media/
|-- logs/                     # Local results/models; excluded from Git
|-- README.md
|-- pyproject.toml
`-- requirements.txt          # Full research dependencies

The layout follows the package/scripts/docs separation used by BlueSky-Gym. Only the environment package is installed into the wheel. Research scripts and generated experiment outputs are maintained separately. Historical results already tracked in Git are retained under logs/; new, untracked experiment outputs are ignored.

Experiments

python scripts/train.py --algorithms ppo a2c --seeds 12345
python scripts/simulate.py --algorithm ppo --num_episodes 3
python scripts/aggregate_results.py --help
python scripts/plot_comparison.py

See scripts/README.md and docs/experiments.md.

Usage

The package follows the same usage pattern as third-party Gymnasium libraries:

import gymnasium as gym
import cleaning_robots_gym

cleaning_robots_gym.register_envs()
env = gym.make("CleaningRobots-v0")

obs, info = env.reset(seed=12345)
terminated = truncated = False
while not (terminated or truncated):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
env.close()

CleaningRobots-v0 loads cleaning_robots_gym/config/cleaning_robots_v0.yaml, which is the single 7x7 journal configuration previously kept as config_2.yaml.

RecordVideo

Gymnasium records videos from environments that support render_mode="rgb_array". Install moviepy if Gymnasium asks for it, then wrap the environment:

import gymnasium as gym
from gymnasium.wrappers import RecordVideo
import cleaning_robots_gym

cleaning_robots_gym.register_envs()

env = gym.make("CleaningRobots-v0", render_mode="rgb_array")
env = RecordVideo(
    env,
    video_folder="logs/videos",
    episode_trigger=lambda episode_id: True,
    name_prefix="cleaning-robots-v0",
)

obs, info = env.reset(seed=12345)
terminated = truncated = False
while not (terminated or truncated):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)

env.close()

For a ready-to-run example, use:

python scripts/record_video.py --episodes 1 --steps_per_episode 500

License and Releases

The code is licensed under the MIT License. Copyright is attributed to Cleaning Robots Gym contributors; the lab affiliation above does not establish institutional ownership of every contribution.

See the release guide for TestPyPI, Trusted Publishing, version updates, and the journal release checklist.