[](https://badge.fury.io/py/gymnasium-robotics)
[](https://badge.fury.io/py/gymnasium-robotics)
[](https://pre-commit.com/)
[](https://github.com/psf/black)
<p align="center">
<img src="https://raw.githubusercontent.com/Farama-Foundation/Gymnasium-Robotics/main/gymrobotics-revised-text.png" width="500px"/>
</p>
This library contains a collection of Reinforcement Learning robotic environments that use the [Gymansium](https://gymnasium.farama.org/) API. The environments run with the [MuJoCo](https://mujoco.org/) physics engine and the maintained [mujoco python bindings](https://mujoco.readthedocs.io/en/latest/python.html).
The documentation website is at [robotics.farama.org](https://robotics.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/YymmHrvS](https://discord.gg/YymmHrvS)
## Installation
To install the Gymnasium-Robotics environments use `pip install gymnasium-robotics`
These environments also require the MuJoCo engine from Deepmind to be installed. Instructions to install the physics engine can be found at the [MuJoCo website](https://mujoco.org/) and the [MuJoCo Github repository](https://github.com/deepmind/mujoco).
Note that the latest environment versions use the latest mujoco python bindings maintained by the MuJoCo team. If you wish to use the old versions of the environments that depend on [mujoco-py](https://github.com/openai/mujoco-py), please install this library with `pip install gymnasium-robotics[mujoco-py]`
We support and test for Linux and macOS. We will accept PRs related to Windows, but do not officially support it.
## Environments
`Gymnasium-Robotics` includes the following groups of environments:
* [Fetch](https://robotics.farama.org/envs/fetch/) - A collection of environments with a 7-DoF robot arm that has to perform manipulation tasks such as Reach, Push, Slide or Pick and Place.
* [Shadow Dexterous Hand](https://robotics.farama.org/envs/shadow_dexterous_hand/) - A collection of environments with a 24-DoF anthropomorphic robotic hand that has to perform object manipulation tasks with a cube, egg-object, or pen. There are variations of these environments that also include data from 92 touch sensors in the observation space.
* [MaMuJoCo](https://robotics.farama.org/envs/MaMuJoCo/) - A collection of multi agent factorizations of the [Gymnasium/MuJoCo](https://gymnasium.farama.org/environments/mujoco/) environments and a framework for factorizing robotic environments, uses the [pettingzoo.ParallelEnv](https://pettingzoo.farama.org/api/parallel/) API.
The [D4RL](https://github.com/Farama-Foundation/D4RL) environments are now available. These environments have been refactored and may not have the same action/observation spaces as the original, please read their documentation:
* [Maze Environments](https://robotics.farama.org/envs/maze/) - An agent has to navigate through a maze to reach certain goal position. Two different agents can be used: a 2-DoF force-controlled ball, or the classic `Ant` agent from the [Gymnasium MuJoCo environments](https://gymnasium.farama.org/environments/mujoco/ant/). The environment can be initialized with a variety of maze shapes with increasing levels of difficulty.
* [Adroit Arm](https://robotics.farama.org/envs/adroit_hand/) - A collection of environments that use the Shadow Dexterous Hand with additional degrees of freedom for the arm movement.
The different tasks involve hammering a nail, opening a door, twirling a pen, or picking up and moving a ball.
* [Franka Kitchen](https://robotics.farama.org/envs/franka_kitchen/) - Multitask environment in which a 9-DoF Franka robot is placed in a kitchen containing several common household items. The goal of each task is to interact with the items in order to reach a desired goal configuration.
**WIP**: generate new `D4RL` environment datasets with [Minari](https://github.com/Farama-Foundation/Minari).
## Multi-goal API
The robotic environments use an extension of the core Gymansium API by inheriting from [GoalEnv](https://robotics.farama.org/content/multi-goal_api/) class. The new API forces the environments to have a dictionary observation space that contains 3 keys:
* `observation` - The actual observation of the environment
* `desired_goal` - The goal that the agent has to achieved
* `achieved_goal` - The goal that the agent has currently achieved instead. The objective of the environments is for this value to be close to `desired_goal`
This API also exposes the function of the reward, as well as the terminated and truncated signals to re-compute their values with different goals. This functionality is useful for algorithms that use Hindsight Experience Replay (HER).
The following example demonstrates how the exposed reward, terminated, and truncated functions
can be used to re-compute the values with substituted goals. The info dictionary can be used to store
additional information that may be necessary to re-compute the reward, but that is independent of the
goal, e.g. state derived from the simulation.
```python
import gymnasium as gym
env = gym.make("FetchReach-v3")
env.reset()
obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
# The following always has to hold:
assert reward == env.compute_reward(obs["achieved_goal"], obs["desired_goal"], info)
assert truncated == env.compute_truncated(obs["achieved_goal"], obs["desired_goal"], info)
assert terminated == env.compute_terminated(obs["achieved_goal"], obs["desired_goal"], info)
# However goals can also be substituted:
substitute_goal = obs["achieved_goal"].copy()
substitute_reward = env.compute_reward(obs["achieved_goal"], substitute_goal, info)
substitute_terminated = env.compute_terminated(obs["achieved_goal"], substitute_goal, info)
substitute_truncated = env.compute_truncated(obs["achieved_goal"], substitute_goal, info)
```
The `GoalEnv` class can also be used for custom environments.
## Project Maintainers
Main Contributors: [Rodrigo Perez-Vicente](https://github.com/rodrigodelazcano), [Kallinteris Andreas](https://github.com/Kallinteris-Andreas), [Jet Tai](https://github.com/jjshoots)
Maintenance for this project is also contributed by the broader Farama team: [farama.org/team](https://farama.org/team).
## Citation
If you use this in your research, please cite:
```
@software{gymnasium_robotics2023github,
author = {Rodrigo de Lazcano and Kallinteris Andreas and Jun Jet Tai and Seungjae Ryan Lee and Jordan Terry},
title = {Gymnasium Robotics},
url = {http://github.com/Farama-Foundation/Gymnasium-Robotics},
version = {1.3.1},
year = {2024},
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "gymnasium-robotics",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Reinforcement Learning, Gymnasium, RL, AI, Robotics",
"author": null,
"author_email": "Farama Foundation <contact@farama.org>",
"download_url": "https://files.pythonhosted.org/packages/e0/15/d34bd865816f46df6c91b60e9b9e7d01ea319d0273217f35a6f9de93040e/gymnasium_robotics-1.3.1.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/gymnasium-robotics)\n[](https://badge.fury.io/py/gymnasium-robotics)\n[](https://pre-commit.com/)\n[](https://github.com/psf/black)\n\n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/Farama-Foundation/Gymnasium-Robotics/main/gymrobotics-revised-text.png\" width=\"500px\"/>\n</p>\n\nThis library contains a collection of Reinforcement Learning robotic environments that use the [Gymansium](https://gymnasium.farama.org/) API. The environments run with the [MuJoCo](https://mujoco.org/) physics engine and the maintained [mujoco python bindings](https://mujoco.readthedocs.io/en/latest/python.html).\n\nThe documentation website is at [robotics.farama.org](https://robotics.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/YymmHrvS](https://discord.gg/YymmHrvS)\n\n## Installation\n\nTo install the Gymnasium-Robotics environments use `pip install gymnasium-robotics`\n\nThese environments also require the MuJoCo engine from Deepmind to be installed. Instructions to install the physics engine can be found at the [MuJoCo website](https://mujoco.org/) and the [MuJoCo Github repository](https://github.com/deepmind/mujoco).\n\nNote that the latest environment versions use the latest mujoco python bindings maintained by the MuJoCo team. If you wish to use the old versions of the environments that depend on [mujoco-py](https://github.com/openai/mujoco-py), please install this library with `pip install gymnasium-robotics[mujoco-py]`\n\nWe support and test for Linux and macOS. We will accept PRs related to Windows, but do not officially support it.\n\n## Environments\n\n`Gymnasium-Robotics` includes the following groups of environments:\n\n* [Fetch](https://robotics.farama.org/envs/fetch/) - A collection of environments with a 7-DoF robot arm that has to perform manipulation tasks such as Reach, Push, Slide or Pick and Place.\n* [Shadow Dexterous Hand](https://robotics.farama.org/envs/shadow_dexterous_hand/) - A collection of environments with a 24-DoF anthropomorphic robotic hand that has to perform object manipulation tasks with a cube, egg-object, or pen. There are variations of these environments that also include data from 92 touch sensors in the observation space.\n* [MaMuJoCo](https://robotics.farama.org/envs/MaMuJoCo/) - A collection of multi agent factorizations of the [Gymnasium/MuJoCo](https://gymnasium.farama.org/environments/mujoco/) environments and a framework for factorizing robotic environments, uses the [pettingzoo.ParallelEnv](https://pettingzoo.farama.org/api/parallel/) API.\n\nThe [D4RL](https://github.com/Farama-Foundation/D4RL) environments are now available. These environments have been refactored and may not have the same action/observation spaces as the original, please read their documentation:\n\n* [Maze Environments](https://robotics.farama.org/envs/maze/) - An agent has to navigate through a maze to reach certain goal position. Two different agents can be used: a 2-DoF force-controlled ball, or the classic `Ant` agent from the [Gymnasium MuJoCo environments](https://gymnasium.farama.org/environments/mujoco/ant/). The environment can be initialized with a variety of maze shapes with increasing levels of difficulty.\n* [Adroit Arm](https://robotics.farama.org/envs/adroit_hand/) - A collection of environments that use the Shadow Dexterous Hand with additional degrees of freedom for the arm movement.\nThe different tasks involve hammering a nail, opening a door, twirling a pen, or picking up and moving a ball.\n* [Franka Kitchen](https://robotics.farama.org/envs/franka_kitchen/) - Multitask environment in which a 9-DoF Franka robot is placed in a kitchen containing several common household items. The goal of each task is to interact with the items in order to reach a desired goal configuration.\n\n**WIP**: generate new `D4RL` environment datasets with [Minari](https://github.com/Farama-Foundation/Minari).\n\n## Multi-goal API\n\nThe robotic environments use an extension of the core Gymansium API by inheriting from [GoalEnv](https://robotics.farama.org/content/multi-goal_api/) class. The new API forces the environments to have a dictionary observation space that contains 3 keys:\n\n* `observation` - The actual observation of the environment\n* `desired_goal` - The goal that the agent has to achieved\n* `achieved_goal` - The goal that the agent has currently achieved instead. The objective of the environments is for this value to be close to `desired_goal`\n\nThis API also exposes the function of the reward, as well as the terminated and truncated signals to re-compute their values with different goals. This functionality is useful for algorithms that use Hindsight Experience Replay (HER).\n\nThe following example demonstrates how the exposed reward, terminated, and truncated functions\ncan be used to re-compute the values with substituted goals. The info dictionary can be used to store\nadditional information that may be necessary to re-compute the reward, but that is independent of the\ngoal, e.g. state derived from the simulation.\n\n```python\nimport gymnasium as gym\n\nenv = gym.make(\"FetchReach-v3\")\nenv.reset()\nobs, reward, terminated, truncated, info = env.step(env.action_space.sample())\n\n# The following always has to hold:\nassert reward == env.compute_reward(obs[\"achieved_goal\"], obs[\"desired_goal\"], info)\nassert truncated == env.compute_truncated(obs[\"achieved_goal\"], obs[\"desired_goal\"], info)\nassert terminated == env.compute_terminated(obs[\"achieved_goal\"], obs[\"desired_goal\"], info)\n\n# However goals can also be substituted:\nsubstitute_goal = obs[\"achieved_goal\"].copy()\nsubstitute_reward = env.compute_reward(obs[\"achieved_goal\"], substitute_goal, info)\nsubstitute_terminated = env.compute_terminated(obs[\"achieved_goal\"], substitute_goal, info)\nsubstitute_truncated = env.compute_truncated(obs[\"achieved_goal\"], substitute_goal, info)\n```\n\nThe `GoalEnv` class can also be used for custom environments.\n\n## Project Maintainers\nMain Contributors: [Rodrigo Perez-Vicente](https://github.com/rodrigodelazcano), [Kallinteris Andreas](https://github.com/Kallinteris-Andreas), [Jet Tai](https://github.com/jjshoots)\n\nMaintenance for this project is also contributed by the broader Farama team: [farama.org/team](https://farama.org/team).\n\n## Citation\n\nIf you use this in your research, please cite:\n```\n@software{gymnasium_robotics2023github,\n author = {Rodrigo de Lazcano and Kallinteris Andreas and Jun Jet Tai and Seungjae Ryan Lee and Jordan Terry},\n title = {Gymnasium Robotics},\n url = {http://github.com/Farama-Foundation/Gymnasium-Robotics},\n version = {1.3.1},\n year = {2024},\n}\n```\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Robotics environments for the Gymnasium repo.",
"version": "1.3.1",
"project_urls": {
"Bug Report": "https://github.com/Farama-Foundation/Gymnasium-Robotics/issues",
"Documentation": "https://robotics.farama.org",
"Homepage": "https://farama.org",
"Repository": "https://github.com/Farama-Foundation/Gymnasium-Robotics"
},
"split_keywords": [
"reinforcement learning",
" gymnasium",
" rl",
" ai",
" robotics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fa7f6374f715410e9272559ed66d28a4ad75fe84b3c53350bca82ebee586d2b1",
"md5": "08dd4ec6803aedb621bb32c291bd634b",
"sha256": "c1f27232827336a244dcf537787077d6db4d4355cfcdf5c922ff260ee311f147"
},
"downloads": -1,
"filename": "gymnasium_robotics-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "08dd4ec6803aedb621bb32c291bd634b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26140530,
"upload_time": "2024-10-14T01:26:50",
"upload_time_iso_8601": "2024-10-14T01:26:50.770833Z",
"url": "https://files.pythonhosted.org/packages/fa/7f/6374f715410e9272559ed66d28a4ad75fe84b3c53350bca82ebee586d2b1/gymnasium_robotics-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e015d34bd865816f46df6c91b60e9b9e7d01ea319d0273217f35a6f9de93040e",
"md5": "e0d48f9d113e36baa57ccc2b50a06639",
"sha256": "574150d79d34d231b840d8ae68aea8992ca9baa99a07bf5efb4a737fe328f378"
},
"downloads": -1,
"filename": "gymnasium_robotics-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "e0d48f9d113e36baa57ccc2b50a06639",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26065462,
"upload_time": "2024-10-14T01:26:54",
"upload_time_iso_8601": "2024-10-14T01:26:54.435065Z",
"url": "https://files.pythonhosted.org/packages/e0/15/d34bd865816f46df6c91b60e9b9e7d01ea319d0273217f35a6f9de93040e/gymnasium_robotics-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-14 01:26:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Farama-Foundation",
"github_project": "Gymnasium-Robotics",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gymnasium-robotics"
}
JSON
