Shimmy is an API conversion tool providing Gymnasium and PettingZoo bindings for popular external reinforcement learning environments.
The documentation website is at shimmy.farama.org and we have a public discord server (which we also use to coordinate development work) that you can join here: https://discord.gg/nhvKkYa6qX
Supported APIs
OpenAI Gym
- Bindings to convert OpenAI Gym environments to Gymnasium.
Atari Environments for OpenAI Gym
DeepMind Control
- Bindings to convert DM Control environments to Gymnasium.
DeepMind Control: Multi-Agent
- Bindings to convert DM Control Soccer environments to PettingZoo.
DMLab
- Bindings to convert DM Lab environments to PettingZoo.
OpenSpiel
- Bindings to convert OpenSpiel environments to PettingZoo.
Behavior Suite
- Bindings to convert Behavior Suite environments to Gymnasium.
Melting Pot
- Bindings to convert Melting Pot environments to PettingZoo.
Installation and Usage
To install Shimmy from PyPI:
pip install shimmy
To install required dependencies for environments, specify them as follows:
pip install shimmy[bsuite, atari]
Choices: gym-v21, gym-v26, atari, bsuite, dm-control, dm-control-multi-agent, openspiel, meltingpot
For development and testing:
pip install shimmy[all, testing]
At a glance
This is an example of using Shimmy to convert DM Control environments into a Gymnasium compatible environment:
import gymnasium as gym
from shimmy.registration import DM_CONTROL_SUITE_ENVS
env_ids = [f"dm_control/{'-'.join(item)}-v0" for item in DM_CONTROL_SUITE_ENVS]
print(env_ids)
env = gym.make(env_ids[0])
env_flatten = gym.wrappers.FlattenObservation(env)
print(env_ids[0])
print("===đ", env.observation_space)
print("===đšī¸", env.action_space)
print("---flattened đ", env_flatten.observation_space)
print("---flattened đšī¸", env_flatten.action_space)['dm_control/acrobot-swingup-v0', 'dm_control/acrobot-swingup_sparse-v0', 'dm_control/ball_in_cup-catch-v0', 'dm_control/cartpole-balance-v0', 'dm_control/cartpole-balance_sparse-v0', 'dm_control/cartpole-swingup-v0', 'dm_control/cartpole-swingup_sparse-v0', 'dm_control/cartpole-two_poles-v0', 'dm_control/cartpole-three_poles-v0', 'dm_control/cheetah-run-v0', 'dm_control/dog-stand-v0', 'dm_control/dog-walk-v0', 'dm_control/dog-trot-v0', 'dm_control/dog-run-v0', 'dm_control/dog-fetch-v0', 'dm_control/finger-spin-v0', 'dm_control/finger-turn_easy-v0', 'dm_control/finger-turn_hard-v0', 'dm_control/fish-upright-v0', 'dm_control/fish-swim-v0', 'dm_control/hopper-stand-v0', 'dm_control/hopper-hop-v0', 'dm_control/humanoid-stand-v0', 'dm_control/humanoid-walk-v0', 'dm_control/humanoid-run-v0', 'dm_control/humanoid-run_pure_state-v0', 'dm_control/humanoid_CMU-stand-v0', 'dm_control/humanoid_CMU-run-v0', 'dm_control/lqr-lqr_2_1-v0', 'dm_control/lqr-lqr_6_2-v0', 'dm_control/manipulator-bring_ball-v0', 'dm_control/manipulator-bring_peg-v0', 'dm_control/manipulator-insert_ball-v0', 'dm_control/manipulator-insert_peg-v0', 'dm_control/pendulum-swingup-v0', 'dm_control/point_mass-easy-v0', 'dm_control/point_mass-hard-v0', 'dm_control/quadruped-walk-v0', 'dm_control/quadruped-run-v0', 'dm_control/quadruped-escape-v0', 'dm_control/quadruped-fetch-v0', 'dm_control/reacher-easy-v0', 'dm_control/reacher-hard-v0', 'dm_control/stacker-stack_2-v0', 'dm_control/stacker-stack_4-v0', 'dm_control/swimmer-swimmer6-v0', 'dm_control/swimmer-swimmer15-v0', 'dm_control/walker-stand-v0', 'dm_control/walker-walk-v0', 'dm_control/walker-run-v0']
dm_control/acrobot-swingup-v0
===đ Dict('orientations': Box(-inf, inf, (4,), float64), 'velocity': Box(-inf, inf, (2,), float64))
===đšī¸ Box(-1.0, 1.0, (1,), float64)
---flattened đ Box(-inf, inf, (6,), float64)
---flattened đšī¸ Box(-1.0, 1.0, (1,), float64)See Basic Usage for more information.
Project Maintainers
Project Manager: Elliot Tower
Core Contributors: Jet Tai, Mark Towers
Maintenance for this project is also contributed by the broader Farama team: farama.org/team.
Citation
If you use Shimmy in your research, please cite:
@software{jun_jet_tai_2023_8140744,
author = {Jun Jet Tai and
Mark Towers and
Elliot Tower},
title = {{Shimmy: Gymnasium and PettingZoo Wrappers for
Commonly Used Environments}},
month = jun,
year = 2023,
publisher = {Zenodo},
version = {v1.1.0},
doi = {10.5281/zenodo.8140744},
url = {https://doi.org/10.5281/zenodo.8140744}
}