Shimmy 2.0.0

This release updates Shimmy to support Gymnasium >= 1.0.0a1. Most importantly, this affects how environments are registered using Shimmy and Atari is now removed (don’t worry, ale-py now natively supports Gymnasium so there is just no need for Shimmy to do this anymore).

In Gymnasium < 1.0, python modules could configure themselves to be loaded on import gymnasium removing the need for import shimmy, however, behind the scenes, this caused significant issues. Therefore, the development team took the decision to remove this feature from Gymnasium v1.0. Moving forward, using Shimmy, users must import shimmy for environments to be registered to then be created. For example,

import gymnasium as gym
import shimmy  # this is now necessary

gym.register_envs(shimmy)  # unnecessary but prevents IDEs from complaining

env = gym.make("dm_control/swingup-v0", render_mode="human")

obs, info = env.reset()
episode_over = False
while not episode_over:
	action = policy(obs)  # replace with actual policy
	obs, reward, terminated, truncated, info = env.step(action)
	episode_over = terminated or truncated
env.close()

Full Changelog: v1.3.0...v2.0.0

Shimmy 1.3.0

Shimmy 1.3.0 Release Notes:

This release updates Shimmy's Melting Pot wrapper to use Melting Pot's pypi release, and includes a minor rendering bugfix for dm_control,

• Note: Melting Pot requires python version >= 3.10, please upgrade your python installation if you intend to use this wrapper

Breaking Changes

• install_melting_pot.sh has been removed, as it is no longer necessary for installation because we are using Melting Pot's pypi release
  • To install all required dependencies, simply run pip install shimmy[meltingpot]

New Features and Improvements

• Update Melting Pot wrapper to use pypi release (#111)

Bug Fixes

• Fix dm_control rendering bug when human mode is used by (#104)

Contributors

@elliottower, @pseudo-rnd-thoughts, @spiglerg @KaleabTessera

Full Changelog: v1.2.1...v1.3.0

Shimmy 1.2.1

Shimmy 1.2.1 Release Notes:

This is a minor hotfix which solves an issue where the Melting Pot dockerfile was not running successfully, leading to CI failures and making our install scripts fail.

Note: DeepMind is working towards fully pip-installable modules for dmlab2d (link)and meltingpot (link), but both are currently in pre-release alpha stage, and currently are not fully functional for our usage.

Bug Fixes

• Fix meltingpot dockerfile (#102)
• Fix meltingpot install script (#103)

Full Changelog: v1.2.0...v1.2.1

Shimmy 1.2.0

Shimmy 1.2.0 Release Notes:

This release drops Python 3.7 support in favor of Python 3.11, updates the OpenSpiel wrapper to be fully consistent with PettingZoo including seeding and observation/action spaces, and includes some minor documentation updates. This release also fixes minor compatibility issues with Gymnasium 0.29.0 and PettingZoo 1.24.0, which is being released alongside this release.

Breaking Changes

• Python 3.7 has reached its end of life support (link), therefore, we have dropped support for it in favor of 3.11.
• Observation spaces and action spaces in OpenSpiel wrapper are now indexed by agent name, rather than agent ID, to match PettingZoo
  • This brings the wrapper to fully match PettingZoo's environment format, enabling easier usage with wrappers and external training libraries

New Features and Improvements

• Python 3.11 support has been added (#100)
• Update pre-commit config to match Gymnasium (#99)
  • CI now ensures proper formatting for toml and yml files, checks that shell scripts have shebangs and can be executed, etc.

Bug Fixes

• OpenSpiel wrapper: fix obs/action space, seeding, and reset config (#96)
• OpenSpiel wrapper: fix calling reset() with no seed, make obs/act spaces fully match PettingZoo (#97)

Documentation Updates

• Add badges: pre-commit, black, DOI badge from Zenodo (#95)
• Fix documentation for installing multiple extras to be correct syntax (#93)

Full Changelog: v1.1.0...v1.2.0

Shimmy 1.1.0

Shimmy 1.1.0 Release Notes:

This is a small bug fix release which fixes rendering issues in the dm-control compatibility wrapper.

Breaking changes

• The dm-control compatibility environment used the env.control_timesteps() for the render frames per second (render_fps), however, this value is the interval between actions per seconds, i.e., 0.04. This was fixed to be the actual fps, by multiplying by 1000. (#91)
• A dt attribute was added to the dm-control compatibility environment that is equivalent to the mujoco environment dt attribute. (#91)
• Modified the rendering in dm-control compatibility, removing render_height, render_width, camera_id and scene_callback in favor of render_kwargs. (#92)
  • As such users should specify kwargs in the dm-control engine render function, i.e., height, width, camera_id and scene_callback.
  • Additionally, this will use the default dm-control arguments unless overridden by the user render_kwargs.

Full Changelog: v1.0.1...v1.1.0

Shimmy 1.0.1

Shimmy 1.0.1 Release Notes:

This release is a small hotfix which updates the multi-agent environments to PettingZoo 1.23.0, and fixes seeding issues with OpenSpiel and DM control multi-agent. It also fixes setup.py to properly install gym v21, and updates testing accordingly. Documentation updates include minor quality of life changes.

Bug Fixes

• Update DM control multi agent and melting pot to PettingZoo 1.23.0 API, fix seeding (#87)
• Update OpenSpiel to PettingZoo 1.23.0 API, fix API test & seeding (#80)
• Fix setup.py for gym v21 (#88)

Documentation Updates

• Allow users to view source code of referenced objects on the website (#78)
• Add text logo to homepage, matching other Farama sites (#79)
• Fix homepage mobile images being squished (#81)
• Fix typo on homepage image grid (#86)
• Create CITATION.cff to allow easier citation of the repository (#83)

Full Changelog: v1.0.0...v1.0.1

Shimmy 1.0.0: Shimmy Becomes Mature

Shimmy 1.0.0 Release Notes:

We are excited to announce the mature release of Shimmy, an API compatibility tool for converting external RL environments to the Gymnasium and PettingZoo APIs. This allows users to access a wide range of single and multi-agent environments, all under a single standard API.

Within Reinforcement learning (RL), a number of API's are used to implement environments, with limited ability to convert between them. This makes training agents across different APIs highly difficult. Shimmy addresses this issue by integrating a range of APIs into the Farama ecosystem. This is part of the Farama Foundation's greater goal of creating a unified and user-friendly ecosystem for open-source reinforcement learning software, for both research and industry.

We plan to maintain Shimmy for the long term, and are welcome to new contributions or suggestions. Future plans include general DM Env and DM lab2d support, and additional environments such as ai-safety-gridworlds.

Shimmy's documentation can be found at shimmy.farama.org. This includes an overview of each environment with screenshots, installation instructions, full usage scripts, and API information.

Environments

Single-agent (Gymnasium wrappers):

• Arcade Learning Environments
• DeepMind Behavior Suite
• DeepMind Control
• DeepMind Lab
• OpenAI Gym - V21
• OpenAI Gym - V26 (breaking API change)

Multi-agent (PettingZoo wrappers):

• DeepMind OpenSpiel
• DeepMind Control: Soccer
• DeepMind Melting Pot

Single-agent environments can be easily loaded using Gymnasium’s registry and make() function as follows:

import gymnasium as gym
env = gym.make("dm_control/acrobot-swingup_sparse-v0", render_mode="human")

Multi-agent environments can be loaded with PettingZoo as follows:

from shimmy import MeltingPotCompatibilityV0
env = MeltingPotCompatibilityV0(substrate_name="prisoners_dilemma_in_the_matrix__arena", render_mode="human")

Breaking Changes

OpenspielCompatibilityV0 has been renamed to OpenSpielCompatibilityV0 (correct spelling of OpenSpiel)

Since the v0.21.0 release, the setup.py has been updated to include separate install options for gym V21 and V26:

• Instead of pip install shimmy[gym], you must select either: pip install shimmy[gym-v21] or pip install shimmy[gym-v26]

New Features and Improvements

This release adds support for three additional environments:

• DeepMind Lab (single-agent)
• DeepMind Behavior Suite (single-agent)
• DeepMind Melting Pot (multi-agent)

This release also expands automated testing to cover each environment (#51) and adds pickling tests (#53), ensuring that each environment can be serialized/deserialized via pickle.

Dockerfiles have been expanded to cover each environment (#52), located in /bin/. These are primarily used for automated testing, but can also be used locally (#65), allowing environments to be used on any platform (see Getting Started: Docker for more information).

The DeepMind Lab and Melting Pot environments are not available in distributed releases (via PyPi or elsewhere), and thus cannot be easily installed via pip install. For these environments, we provide full installation scripts for both MacOS and Linux.

• /scripts/install_dm_lab.sh
• /scripts/install_melting_pot.sh

Bug Fixes and Documentation Updates

This release includes a major documentation overhaul, updating the project to comply with Farama Project Standards (#66). This includes a Getting Started page, with installation information, and a Basic Usage page, with reference information on using both single- and multi-agent environments.

Documentation has also been standardized to include descriptions of each environment, with links to documentation and related libraries, and images of the environment for reference (#43, #47 #49).

Full example usage scripts are now provided for each environment, allowing users to easily load and interact with an environment without prior knowledge.

Example: run a dm-control environment:

observation, info = env.reset(seed=42)
for _ in range(1000):
   action = env.action_space.sample()  # this is where you would insert your policy
   observation, reward, terminated, truncated, info = env.step(action)

   if terminated or truncated:
      observation, info = env.reset()
env.close()

Full Changelog: v0.2.1...v1.0.0

v0.2.1

Release

This is a minor release that fixes several bugs in dm-control, compatibility with gym v0.21 along with bumping dm-control to 1.0.10 and ale-py to 0.8.1.
Additionally, this changes GymV22Environment to GymV21Environment as the environment always implemented gym's v0.21 API rather than v0.22. Furthermore, removes a warning previously introduced in gymnasium v0.27.1.

Bug Fixes

• Fixed dm-control step termination and truncation, previously this was the opposite of the specification by @pseudo-rnd-thoughts and @ottofabianin in #30
• Check if the default wrappers exist before stripping for compatibility with Gym v0.21 by @nuance1979 in #34
• Update the list of dm-control environments for 1.0.10 to include humanoid-cmu talk by @pseudo-rnd-thoughts in #36
• Remove warning that GymV22Environment and GymV26Environment are overwritten and change V22 to V21 in the GymV22Environment by @pseudo-rnd-thoughts in #29
• Bump ale-py to v0.8.1 which includes a number of bug fixes by @pseudo-rnd-thoughts in #37. For all the changes, read the release notes.

Finally, @jjshoots and @SiddarGu updated the documentation in #28 and #25 respectively.

Full Changelog: v0.2.0...v0.2.1

v0.2.0

Release notes

We update Shimmy for Gymnasium v0.27 and this release is not compatible with v0.26 with dm-control due to the Gymnasium Mujoco rendering changing.

New environments supported: dm-lab and dm-control multiagent (soccer)

Changes

• Add some friendly docs on how to get started by @vwxyzjn in #20
• Update gym compatibility environment names by @pseudo-rnd-thoughts in #16
• Add dm-lab (no tests yet) and dm-control-multiagent by @jjshoots in #7
• Add __getattr__ to Gym compatibility env to fix atari preprocessing issue, add registration of dm-lab compatibility environment. by @pseudo-rnd-thoughts in #22

New Contributors

• @vwxyzjn made their first contribution in #20

Full Changelog: v0.1.0...v0.2.0

v0.1.0 (Initial release)

Shimmy aims to provide compatibility for reinforcement learning environments to be compatible with Gymnasium or PettingZoo.

In this initial release, we provide compatibility for

• OpenAI Gym: We provide compatibility environments for V22 and V26 environments, GymV22Environment-v0 and GymV26Environment-v0
• dm-control: suite, manipulation and locomotion (currently the soccer environments are not supported)
• atari: As ale-py had not added gymnasium support yet, shimmy adds the AtariEnv with a couple of very minor changes that are backward compatible with the gym environments.
• openspiel: We support a large number of the environments, however not all of them

We aim to have a website soon with install instructions for the different environments in the next few weeks

We are interested in supporting more environment APIs, please add a comment on #2