We are excited to announce the mature release of [Shimmy](https://shimmy.farama.org/), an API compatibility tool for converting external RL environments to the [Gymnasium](https://gymnasium.farama.org/) and [PettingZoo](https://pettingzoo.farama.org/) 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](https://farama.org/)'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](https://github.com/deepmind/dm_env) and [DM lab2d](https://github.com/deepmind/lab2d) support, and additional environments such as [ai-safety-gridworlds](https://github.com/deepmind/ai-safety-gridworlds).
Shimmy's documentation can be found at [shimmy.farama.org](https://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](https://github.com/mgbellemare/Arcade-Learning-Environment)
* [DeepMind Behavior Suite](https://shimmy.farama.org/contents/bsuite/)
* [DeepMind Control](https://github.com/deepmind/dm_control/)
* [DeepMind Lab](https://github.com/deepmind/lab)
* [OpenAI Gym](https://github.com/openai/gym) - [V21](https://github.com/openai/gym/releases/tag/v0.21.0)
* [OpenAI Gym](https://github.com/openai/gym) - [V26](https://github.com/openai/gym/releases/tag/0.26.0) (breaking API change)
Multi-agent (PettingZoo wrappers):
* [DeepMind OpenSpiel](https://github.com/deepmind/open_spiel)
* [DeepMind Control: Soccer](https://github.com/deepmind/dm_control/blob/main/dm_control/locomotion/soccer/README.md)
* [DeepMind Melting Pot](https://github.com/deepmind/meltingpot)
Single-agent environments can be easily loaded using Gymnasium’s [registry ](https://gymnasium.farama.org/api/registry/)and `make()` function as follows:
python
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:
python
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](https://github.com/deepmind/open_spiel))
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](https://github.com/deepmind/lab) (single-agent)
* [DeepMind Behavior Suite](https://shimmy.farama.org/contents/bsuite/) (single-agent)
* [DeepMind Melting Pot](https://github.com/deepmind/meltingpot) (multi-agent)
This release also expands automated testing to cover each environment ([51](https://github.com/Farama-Foundation/Shimmy/pull/51)) and adds pickling tests ([#53](https://github.com/Farama-Foundation/Shimmy/pull/53)), ensuring that each environment can be serialized/deserialized via [pickle](https://docs.python.org/3/library/pickle.html).
[Dockerfiles](https://docs.docker.com/engine/reference/builder/) have been expanded to cover each environment ([#52](https://github.com/Farama-Foundation/Shimmy/pull/52)), located in [/bin/](https://github.com/Farama-Foundation/Shimmy/tree/main/bin). These are primarily used for automated testing, but can also be used locally ([#65](https://github.com/Farama-Foundation/Shimmy/pull/65)), allowing environments to be used on any platform (see [Getting Started: Docker](https://shimmy.farama.org/content/getting_started/#docker) for more information).
The [DeepMind Lab](https://github.com/deepmind/lab) and [Melting Pot](https://github.com/deepmind/meltingpot) environments are not available in distributed releases (via [PyPi](https://pypi.org/) or elsewhere), and thus cannot be easily installed via `pip install`. For these environments, we provide full [installation scripts](https://github.com/Farama-Foundation/Shimmy/tree/main/scripts) for both MacOS and Linux.
* [/scripts/install_dm_lab.sh](https://github.com/Farama-Foundation/Shimmy/blob/main/scripts/install_dm_lab.sh)
* [/scripts/install_melting_pot.sh](https://github.com/Farama-Foundation/Shimmy/blob/main/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](https://farama.org/project_standards) ([#66](https://github.com/Farama-Foundation/Shimmy/pull/66)). This includes a [Getting Started](https://shimmy.farama.org/content/getting_started/) page, with installation information, and a [Basic Usage](https://shimmy.farama.org/content/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](https://github.com/Farama-Foundation/Shimmy/pull/43), [#47](https://github.com/Farama-Foundation/Shimmy/pull/47) [#49](https://github.com/Farama-Foundation/Shimmy/pull/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:
python
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**: https://github.com/Farama-Foundation/Shimmy/compare/v0.2.1...v1.0.0