KaleabTessera/Shimmy

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

Bindings to convert ALE-py Atari environments to Gymnasium.

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}
}

KaleabTessera / Shimmy