<div align="center">
<h1>
Safety-Gymnasium
</h1>
</div>
<div align="center">
<a></a>
<a href="https://pypi.org/project/safety-gymnasium"></a>
<a href="https://safety-gymnasium.readthedocs.io"></a>
<a href="https://pepy.tech/project/safety-gymnasium"></a>
<a href="https://github.com/PKU-Alignment/safety-gymnasium/stargazers"></a>
<a href="https://github.com/PKU-Alignment/safety-gymnasium/blob/HEAD/LICENSE"></a>
</div>
<p align="center">
<a href="https://github.com/PKU-Alignment/safety-gymnasium#why-safety-gymnasium">Why Safety-Gymnasium?</a> |
<a href="https://www.safety-gymnasium.com">Documentation</a> |
<a href="https://github.com/PKU-Alignment/safety-gymnasium#installation">Install guide</a> |
<a href="https://github.com/PKU-Alignment/safety-gymnasium#customize-your-environments">Customization</a> | <a href="https://sites.google.com/view/safety-gymnasium">Video</a>
</p>
Safety-Gymnasium is a highly scalable and customizable Safe Reinforcement Learning (SafeRL) library.
It aims to deliver a good view of benchmarking SafeRL algorithms and a standardized set of environments.
We provide a set of standard APIs which are compatible with information on constraints.
Users can explore new insights via an elegant code framework and well-designed environments.
--------------------------------------------------------------------------------
## Why Safety-Gymnasium?
Here we provide a table for comparison of **Safety-Gymnasium** and existing SafeRL Environments libraries.
| SafeRL<br/>Envs | Engine | Vectorized<br/> Environments | New Gym API<sup>**(3)**</sup> | Vision Input |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------: | :--------------------------: | :---------------------------: | :-----------------: |
| [Safety-Gym](https://github.com/openai/safety-gym)<br/> | `mujoco-py`<sup>**(1)**</sup> | ❌ | ❌ | minimally supported |
| [safe-control-gym](https://github.com/utiasDSL/safe-control-gym)<br/> | PyBullet | ❌ | ❌ | ❌ |
| Velocity-Constraints<sup>**(2)**</sup> | N/A | ❌ | ❌ | ❌ | ❌ |
| [mujoco-circle](https://github.com/ymzhang01/mujoco-circle)<br/> | PyTorch | ❌ | ❌ | ❌ | ❌ |
| Safety-Gymnasium<br/> | **MuJoCo 2.3.0+** | ✅ | ✅ | ✅ |
<sup>(1): Maintenance (expect bug fixes and minor updates); the last commit is 19 Nov 2021. Safety-Gym depends on `mujoco-py` 2.0.2.7, which was updated on Oct 12, 2019.</sup><br/>
<sup>(2): There is no official library for speed-related environments, and its associated cost constraints are constructed from info. But the task is widely used in the study of SafeRL, and we encapsulate it in Safety-Gymnasium.</sup><br/>
<sup>(3): In the gym 0.26.0 release update, a new API of interaction was redefined.</sup>
--------------------------------------------------------------------------------
## Environments
We designed a variety of safety-enhanced learning tasks and integrated the contributions from the RL community: `safety-velocity`, `safety-run`, `safety-circle`, `safety-goal`, `safety-button`, etc.
We introduce a unified safety-enhanced learning benchmark environment library called `Safety-Gymnasium.`
Further, to facilitate the progress of community research, we redesigned [Safety-Gym](https://github.com/openai/safety-gym) and removed the dependency on `mujoco-py`.
We built it on top of [MuJoCo](https://github.com/deepmind/mujoco) and fixed some bugs, more specific bug reports can refer to [Safety-Gym's BUG Report](https://github.com/PKU-Alignment/safety-gymnasium/blob/main/safety_gym_bug_report.md).
Here is a list of all the environments we support for now:
<table border="1">
<thead>
<tr>
<th>Category</th>
<th>Task</th>
<th>Agent</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td rowspan="4">Safe Navigation</td>
<td>Button[012]</td>
<td rowspan="4">Point, Car, Doggo, Racecar, Ant</td>
<td rowspan="4">SafetyPointGoal1-v0</td>
</tr>
<tr>
<td>Goal[012]</td>
</tr>
<tr>
<td>Push[012]</td>
</tr>
<tr>
<td>Circle[012]</td>
</tr>
<tr>
<td>Safe Velocity</td>
<td>Velocity</td>
<td>HalfCheetah, Hopper, Swimmer, Walker2d, Ant, Humanoid</td>
<td>SafetyAntVelocity-v1</td>
</tr>
<tr>
<td rowspan="7">Safe Vision</td>
<td>BuildingButton[012]</td>
<td rowspan="7">Point, Car, Doggo, Racecar, Ant</td>
<td rowspan="7">SafetyFormulaOne1-v0</td>
</tr>
<tr>
<td>BuildingGoal[012]</td>
</tr>
<tr>
<td>BuildingPush[012]</td>
</tr>
<tr>
<td>FadingEasy[012]</td>
</tr>
<tr>
<td>FadingHard[012]</td>
</tr>
<tr>
<td>Race[012]</td>
</tr>
<tr>
<td>FormulaOne[012]</td>
</tr>
<tr>
<td rowspan="8">Safe Multi-Agent</td>
<td>MultiGoal[012]</td>
<td>Multi-Point, Multi-Ant</td>
<td>SafetyAntMultiGoal1-v0</td>
</tr>
<tr>
<td>Multi-Agent Velocity</td>
<td>6x1HalfCheetah, 2x3HalfCheetah, 3x1Hopper, 2x1Swimmer, 2x3Walker2d, 2x4Ant, 4x2Ant, 9|8Humanoid</td>
<td>Safety2x4AntVelocity-v0</td>
</tr>
<tr>
<td>FreightFrankaCloseDrawer(Multi-Agent)</td>
<td rowspan="2">FreightFranka</td>
<td rowspan="2">FreightFrankaCloseDrawer(Multi-Agent)</td>
</tr>
<tr>
<td>FreightFrankaPickAndPlace(Multi-Agent)</td>
</tr>
<tr>
<td>ShadowHandCatchOver2UnderarmSafeFinger(Multi-Agent)</td>
<td rowspan="4">ShadowHands</td>
<td rowspan="4">ShadowHandCatchOver2UnderarmSafeJoint(Multi-Agent)</td>
</tr>
<tr>
<td>ShadowHandCatchOver2UnderarmSafeJoint(Multi-Agent)</td>
</tr>
<tr>
<td>ShadowHandOverSafeFinger(Multi-Agent)</td>
</tr>
<tr>
<td>ShadowHandOverSafeJoint(Multi-Agent)</td>
</tr>
<tr>
<td rowspan="6">Safe Isaac Gym</td>
<td>FreightFrankaCloseDrawer</td>
<td rowspan="2">FreightFranka</td>
<td rowspan="2">FreightFrankaCloseDrawer</td>
</tr>
<tr>
<td>FreightFrankaPickAndPlace</td>
</tr>
<tr>
<td>ShadowHandCatchOver2UnderarmSafeFinger</td>
<td rowspan="4">ShadowHands</td>
<td rowspan="4">ShadowHandCatchOver2UnderarmSafeJoint</td>
</tr>
<tr>
<td>ShadowHandCatchOver2UnderarmSafeJoint</td>
</tr>
<tr>
<td>ShadowHandOverSafeFinger</td>
</tr>
<tr>
<td>ShadowHandOverSafeJoint</td>
</tr>
</tbody>
</table>
Here are some screenshots of the **Safe Navigation** tasks.
#### Agents
<table class="docutils align-default">
<tbody>
<tr class="row-odd">
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/point_front.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/point_front.jpeg"
style="width: 130px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="doc">Point</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference" href="agents/car.html"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/car_front.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/car_front.jpeg"
style="width: 130px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="doc">Car</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference" href="agents/racecar.html"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/racecar_front.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/racecar_front.jpeg"
style="width: 130px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="doc">Racecar</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference" href="agents/doggo.html"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/doggo_front.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/doggo_front.jpeg"
style="width: 130px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="doc">Doggo</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference" href="agents/ant.html"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/ant_front.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/ant_front.jpeg"
style="width: 130px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="doc">Ant</span></a></strong>
</p>
</td>
</tr>
</tbody>
</table>
#### Tasks
<table class="docutils align-default">
<tbody>
<tr class="row-odd">
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/goal0.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/goal0.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Goal0</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/goal1.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/goal1.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Goal1</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/goal2.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/goal2.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Goal2</span></a></strong>
</p>
</td>
</tr>
<tr class="row-even">
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/button0.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/button0.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Button0</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference" href="./button#button1"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/button1.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/button1.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Button1</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference" href="./button#button2"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/button2.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/button2.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Button2</span></a></strong>
</p>
</td>
</tr>
<tr class="row-odd">
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/push0.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/push0.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Push0</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/push1.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/push1.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Push1</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/push2.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/push2.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Push2</span></a></strong>
</p>
</td>
</tr>
<tr class="row-even">
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/circle0.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/circle0.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Circle0</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/circle1.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/circle1.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Circle1</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference" href="./circle#circle2"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/circle2.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/circle2.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Circle2</span></a></strong>
</p>
</td>
</tr>
</tbody>
</table>
### Vision-based Safe RL
Vision-based SafeRL lacks realistic scenarios.
Although the original `Safety-Gym` could minimally support visual input, the scenarios were too similar.
To facilitate the validation of visual-based SafeRL algorithms, we have developed a set of realistic vision-based SafeRL tasks, which are currently being validated on the baseline.
For the appetizer, the images are as follows:
<table class="docutils align-default">
<tbody>
<tr class="row-odd">
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/race0.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/race0.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Race0</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/race1.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/race1.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Race1</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/race2.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/race2.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">Race2</span></a></strong>
</p>
</td>
</tr>
<tr class="row-odd">
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/formula_one0.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/formula_one0.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">FormulaOne0</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/formula_one1.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/formula_one1.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">FormulaOne1</span></a></strong>
</p>
</td>
<td>
<figure class="align-default">
<a class="reference external image-reference"><img
alt="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/formula_one2.jpeg"
src="https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/formula_one2.jpeg" style="width: 230px;"></a>
</figure>
<p class="centered">
<strong><a class="reference internal"><span class="std std-ref">FormulaOne2</span></a></strong>
</p>
</td>
</tr>
</tbody>
</table>
### Environment Usage
**Notes:** We support explicitly expressing the `cost` based on [**Gymnasium APIs**](https://github.com/Farama-Foundation/Gymnasium).
The `step` method returns 6 items `(next_obervation, reward, cost, terminated, truncated, info)` with an extra `cost` field.
```python
import safety_gymnasium
env_id = 'SafetyPointGoal1-v0'
env = safety_gymnasium.make(env_id)
obs, info = env.reset()
while True:
act = env.action_space.sample()
obs, reward, cost, terminated, truncated, info = env.step(act)
if terminated or truncated:
break
env.render()
```
We also provide two convenience wrappers for converting the Safety-Gymnasium environment to the standard Gymnasium API and vice versa.
```python
# Safety-Gymnasium API: step returns (next_obervation, reward, cost, terminated, truncated, info)
# Gymnasium API: step returns (next_obervation, reward, terminated, truncated, info) and cost is in the `info` dict associated with a str key `'cost'`
safety_gymnasium_env = safety_gymnasium.make(env_id)
gymnasium_env = safety_gymnasium.wrappers.SafetyGymnasium2Gymnasium(safety_gymnasium_env)
safety_gymnasium_env = safety_gymnasium.wrappers.Gymnasium2SafetyGymnasium(gymnasium_env)
```
Users can apply Gymnasium wrappers easily with:
```python
import gymnasium
import safety_gymnasium
def make_safe_env(env_id):
safe_env = safety_gymnasium.make(env_id)
env = safety_gymnasium.wrappers.SafetyGymnasium2Gymnasium(safe_env)
env = gymnasium.wrappers.SomeWrapper1(env)
env = gymnasium.wrappers.SomeWrapper2(env, argname1=arg1, argname2=arg2)
...
env = gymnasium.wrappers.SomeWrapperN(env)
safe_env = safety_gymnasium.wrappers.Gymnasium2SafetyGymnasium(env)
return safe_env
```
or
```python
import functools
import gymnasium
import safety_gymnasium
def make_safe_env(env_id):
return safety_gymnasium.wrappers.with_gymnasium_wrappers(
safety_gymnasium.make(env_id),
gymnasium.wrappers.SomeWrapper1,
functools.partial(gymnasium.wrappers.SomeWrapper2, argname1=arg1, argname2=arg2),
...,
gymnasium.wrappers.SomeWrapperN,
)
```
In addition, for all Safety-Gymnasium environments, we also provide corresponding Gymnasium environments with a suffix `Gymnasium` in the environment id. For example:
```python
import gymnasium
import safety_gymnasium
safety_gymnasium.make('SafetyPointGoal1-v0') # step returns (next_obervation, reward, cost, terminated, truncated, info)
gymnasium.make('SafetyPointGoal1Gymnasium-v0') # step returns (next_obervation, reward, terminated, truncated, info)
```
--------------------------------------------------------------------------------
## Installation
### Install from PyPI
```bash
pip install safety-gymnasium
```
### Install from source
```bash
conda create -n <envname> python=3.8
conda activate <envname>
git clone https://github.com/PKU-Alignment/safety-gymnasium.git
cd safety-gymnasium
pip install -e .
```
### Important Notes
If you failed to render on your server, you can try:
```bash
echo "export MUJOCO_GL=osmesa" >> ~/.bashrc
source ~/.bashrc
apt-get install libosmesa6-dev
apt-get install python3-opengl
```
--------------------------------------------------------------------------------
## Customize your environments
We construct a highly expandable framework of code so that you can easily comprehend it and design your environments to facilitate your research with no more than 100 lines of code on average.
For details, please refer to our [documentation](https://www.safety-gymnasium.com/en/latest/components_of_environments/tasks/task_example.html).
Here is a minimal example:
```python
# import the objects you want to use
# or you can define specific objects by yourself, just make sure obeying our specification
from safety_gymnasium.assets.geoms import Apples
from safety_gymnasium.bases import BaseTask
# inherit the basetask
class MytaskLevel0(BaseTask):
def __init__(self, config):
super().__init__(config=config)
# define some properties
self.num_steps = 500
self.agent.placements = [(-0.8, -0.8, 0.8, 0.8)]
self.agent.keepout = 0
self.lidar_conf.max_dist = 6
# add objects into environments
self.add_geoms(Apples(num=2, size=0.3))
def calculate_reward(self):
# implement your reward function
# Note: cost calculation is based on objects, so it's automatic
reward = 1
return reward
def specific_reset(self):
# depending on your task
def specific_step(self):
# depending on your task
def update_world(self):
# depending on your task
@property
def goal_achieved(self):
# depending on your task
```
## Citing Safety-Gymnasium
If you find Safety-Gymnasium useful, please cite it in your publications.
```bibtex
@article{Safety-Gymnasium,
author = {Jiaming Ji and Borong Zhang and Xuehai Pan and Jiayi Zhou and Juntao Dai and Yaodong Yang},
title = {Safety-Gymnasium},
year = {2023},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/PKU-Alignment/safety-gymnasium}},
}
```
## License
Safety-Gymnasium is released under Apache License 2.0.
Raw data
{
"_id": null,
"home_page": "",
"name": "safety-gymnasium",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "Safe Reinforcement Learning,RL Environment,MuJoCo",
"author": "Safety-Gymnasium Contributors",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/20/6a/577167d6cc06d98861b4ce77f77256ef3194ab0c55bcbc8b4723a01ac62c/safety-gymnasium-1.2.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n<h1>\n Safety-Gymnasium\n</h1>\n</div>\n\n<div align=\"center\">\n\n <a></a>\n <a href=\"https://pypi.org/project/safety-gymnasium\"></a>\n <a href=\"https://safety-gymnasium.readthedocs.io\"></a>\n <a href=\"https://pepy.tech/project/safety-gymnasium\"></a>\n <a href=\"https://github.com/PKU-Alignment/safety-gymnasium/stargazers\"></a>\n <a href=\"https://github.com/PKU-Alignment/safety-gymnasium/blob/HEAD/LICENSE\"></a>\n\n</div>\n\n<p align=\"center\">\n<a href=\"https://github.com/PKU-Alignment/safety-gymnasium#why-safety-gymnasium\">Why Safety-Gymnasium?</a> |\n <a href=\"https://www.safety-gymnasium.com\">Documentation</a> |\n <a href=\"https://github.com/PKU-Alignment/safety-gymnasium#installation\">Install guide</a> |\n <a href=\"https://github.com/PKU-Alignment/safety-gymnasium#customize-your-environments\">Customization</a> | <a href=\"https://sites.google.com/view/safety-gymnasium\">Video</a>\n</p>\n\nSafety-Gymnasium is a highly scalable and customizable Safe Reinforcement Learning (SafeRL) library.\nIt aims to deliver a good view of benchmarking SafeRL algorithms and a standardized set of environments.\nWe provide a set of standard APIs which are compatible with information on constraints.\nUsers can explore new insights via an elegant code framework and well-designed environments.\n\n--------------------------------------------------------------------------------\n\n## Why Safety-Gymnasium?\n\nHere we provide a table for comparison of **Safety-Gymnasium** and existing SafeRL Environments libraries.\n\n| SafeRL<br/>Envs | Engine | Vectorized<br/> Environments | New Gym API<sup>**(3)**</sup> | Vision Input |\n| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------: | :--------------------------: | :---------------------------: | :-----------------: |\n| [Safety-Gym](https://github.com/openai/safety-gym)<br/> | `mujoco-py`<sup>**(1)**</sup> | \u274c | \u274c | minimally supported |\n| [safe-control-gym](https://github.com/utiasDSL/safe-control-gym)<br/> | PyBullet | \u274c | \u274c | \u274c |\n| Velocity-Constraints<sup>**(2)**</sup> | N/A | \u274c | \u274c | \u274c | \u274c |\n| [mujoco-circle](https://github.com/ymzhang01/mujoco-circle)<br/> | PyTorch | \u274c | \u274c | \u274c | \u274c |\n| Safety-Gymnasium<br/> | **MuJoCo 2.3.0+** | \u2705 | \u2705 | \u2705 |\n\n<sup>(1): Maintenance (expect bug fixes and minor updates); the last commit is 19 Nov 2021. Safety-Gym depends on `mujoco-py` 2.0.2.7, which was updated on Oct 12, 2019.</sup><br/>\n<sup>(2): There is no official library for speed-related environments, and its associated cost constraints are constructed from info. But the task is widely used in the study of SafeRL, and we encapsulate it in Safety-Gymnasium.</sup><br/>\n<sup>(3): In the gym 0.26.0 release update, a new API of interaction was redefined.</sup>\n\n--------------------------------------------------------------------------------\n\n## Environments\n\nWe designed a variety of safety-enhanced learning tasks and integrated the contributions from the RL community: `safety-velocity`, `safety-run`, `safety-circle`, `safety-goal`, `safety-button`, etc.\nWe introduce a unified safety-enhanced learning benchmark environment library called `Safety-Gymnasium.`\n\nFurther, to facilitate the progress of community research, we redesigned [Safety-Gym](https://github.com/openai/safety-gym) and removed the dependency on `mujoco-py`.\nWe built it on top of [MuJoCo](https://github.com/deepmind/mujoco) and fixed some bugs, more specific bug reports can refer to [Safety-Gym's BUG Report](https://github.com/PKU-Alignment/safety-gymnasium/blob/main/safety_gym_bug_report.md).\n\nHere is a list of all the environments we support for now:\n\n<table border=\"1\">\n <thead>\n <tr>\n <th>Category</th>\n <th>Task</th>\n <th>Agent</th>\n <th>Example</th>\n </tr>\n </thead>\n <tbody>\n <tr>\n <td rowspan=\"4\">Safe Navigation</td>\n <td>Button[012]</td>\n <td rowspan=\"4\">Point, Car, Doggo, Racecar, Ant</td>\n <td rowspan=\"4\">SafetyPointGoal1-v0</td>\n </tr>\n <tr>\n <td>Goal[012]</td>\n </tr>\n <tr>\n <td>Push[012]</td>\n </tr>\n <tr>\n <td>Circle[012]</td>\n </tr>\n <tr>\n <td>Safe Velocity</td>\n <td>Velocity</td>\n <td>HalfCheetah, Hopper, Swimmer, Walker2d, Ant, Humanoid</td>\n <td>SafetyAntVelocity-v1</td>\n </tr>\n <tr>\n <td rowspan=\"7\">Safe Vision</td>\n <td>BuildingButton[012]</td>\n <td rowspan=\"7\">Point, Car, Doggo, Racecar, Ant</td>\n <td rowspan=\"7\">SafetyFormulaOne1-v0</td>\n </tr>\n <tr>\n <td>BuildingGoal[012]</td>\n </tr>\n <tr>\n <td>BuildingPush[012]</td>\n </tr>\n <tr>\n <td>FadingEasy[012]</td>\n </tr>\n <tr>\n <td>FadingHard[012]</td>\n </tr>\n <tr>\n <td>Race[012]</td>\n </tr>\n <tr>\n <td>FormulaOne[012]</td>\n </tr>\n <tr>\n <td rowspan=\"8\">Safe Multi-Agent</td>\n <td>MultiGoal[012]</td>\n <td>Multi-Point, Multi-Ant</td>\n <td>SafetyAntMultiGoal1-v0</td>\n </tr>\n <tr>\n <td>Multi-Agent Velocity</td>\n <td>6x1HalfCheetah, 2x3HalfCheetah, 3x1Hopper, 2x1Swimmer, 2x3Walker2d, 2x4Ant, 4x2Ant, 9|8Humanoid</td>\n <td>Safety2x4AntVelocity-v0</td>\n </tr>\n <tr>\n <td>FreightFrankaCloseDrawer(Multi-Agent)</td>\n <td rowspan=\"2\">FreightFranka</td>\n <td rowspan=\"2\">FreightFrankaCloseDrawer(Multi-Agent)</td>\n </tr>\n <tr>\n <td>FreightFrankaPickAndPlace(Multi-Agent)</td>\n </tr>\n <tr>\n <td>ShadowHandCatchOver2UnderarmSafeFinger(Multi-Agent)</td>\n <td rowspan=\"4\">ShadowHands</td>\n <td rowspan=\"4\">ShadowHandCatchOver2UnderarmSafeJoint(Multi-Agent)</td>\n </tr>\n <tr>\n <td>ShadowHandCatchOver2UnderarmSafeJoint(Multi-Agent)</td>\n </tr>\n <tr>\n <td>ShadowHandOverSafeFinger(Multi-Agent)</td>\n </tr>\n <tr>\n <td>ShadowHandOverSafeJoint(Multi-Agent)</td>\n </tr>\n <tr>\n <td rowspan=\"6\">Safe Isaac Gym</td>\n <td>FreightFrankaCloseDrawer</td>\n <td rowspan=\"2\">FreightFranka</td>\n <td rowspan=\"2\">FreightFrankaCloseDrawer</td>\n </tr>\n <tr>\n <td>FreightFrankaPickAndPlace</td>\n </tr>\n <tr>\n <td>ShadowHandCatchOver2UnderarmSafeFinger</td>\n <td rowspan=\"4\">ShadowHands</td>\n <td rowspan=\"4\">ShadowHandCatchOver2UnderarmSafeJoint</td>\n </tr>\n <tr>\n <td>ShadowHandCatchOver2UnderarmSafeJoint</td>\n </tr>\n <tr>\n <td>ShadowHandOverSafeFinger</td>\n </tr>\n <tr>\n <td>ShadowHandOverSafeJoint</td>\n </tr>\n </tbody>\n</table>\n\nHere are some screenshots of the **Safe Navigation** tasks.\n\n#### Agents\n\n<table class=\"docutils align-default\">\n <tbody>\n <tr class=\"row-odd\">\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/point_front.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/point_front.jpeg\"\n style=\"width: 130px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"doc\">Point</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\" href=\"agents/car.html\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/car_front.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/car_front.jpeg\"\n style=\"width: 130px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"doc\">Car</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\" href=\"agents/racecar.html\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/racecar_front.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/racecar_front.jpeg\"\n style=\"width: 130px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"doc\">Racecar</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\" href=\"agents/doggo.html\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/doggo_front.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/doggo_front.jpeg\"\n style=\"width: 130px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"doc\">Doggo</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\" href=\"agents/ant.html\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/ant_front.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/ant_front.jpeg\"\n style=\"width: 130px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"doc\">Ant</span></a></strong>\n </p>\n </td>\n </tr>\n </tbody>\n</table>\n\n#### Tasks\n\n<table class=\"docutils align-default\">\n <tbody>\n <tr class=\"row-odd\">\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/goal0.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/goal0.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Goal0</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/goal1.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/goal1.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Goal1</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/goal2.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/goal2.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Goal2</span></a></strong>\n </p>\n </td>\n </tr>\n <tr class=\"row-even\">\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/button0.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/button0.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Button0</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\" href=\"./button#button1\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/button1.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/button1.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Button1</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\" href=\"./button#button2\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/button2.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/button2.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Button2</span></a></strong>\n </p>\n </td>\n </tr>\n <tr class=\"row-odd\">\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/push0.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/push0.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Push0</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/push1.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/push1.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Push1</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/push2.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/push2.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Push2</span></a></strong>\n </p>\n </td>\n </tr>\n <tr class=\"row-even\">\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/circle0.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/circle0.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Circle0</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/circle1.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/circle1.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Circle1</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\" href=\"./circle#circle2\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/circle2.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/images/circle2.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Circle2</span></a></strong>\n </p>\n </td>\n </tr>\n </tbody>\n</table>\n\n### Vision-based Safe RL\n\nVision-based SafeRL lacks realistic scenarios.\nAlthough the original `Safety-Gym` could minimally support visual input, the scenarios were too similar.\nTo facilitate the validation of visual-based SafeRL algorithms, we have developed a set of realistic vision-based SafeRL tasks, which are currently being validated on the baseline.\n\nFor the appetizer, the images are as follows:\n\n<table class=\"docutils align-default\">\n <tbody>\n <tr class=\"row-odd\">\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/race0.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/race0.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Race0</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/race1.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/race1.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Race1</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/race2.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/race2.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">Race2</span></a></strong>\n </p>\n </td>\n </tr>\n <tr class=\"row-odd\">\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/formula_one0.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/formula_one0.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">FormulaOne0</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/formula_one1.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/formula_one1.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">FormulaOne1</span></a></strong>\n </p>\n </td>\n <td>\n <figure class=\"align-default\">\n <a class=\"reference external image-reference\"><img\n alt=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/formula_one2.jpeg\"\n src=\"https://github.com/PKU-Alignment/safety-gymnasium/raw/HEAD/docs/_static/images/formula_one2.jpeg\" style=\"width: 230px;\"></a>\n </figure>\n <p class=\"centered\">\n <strong><a class=\"reference internal\"><span class=\"std std-ref\">FormulaOne2</span></a></strong>\n </p>\n </td>\n </tr>\n </tbody>\n</table>\n\n### Environment Usage\n\n**Notes:** We support explicitly expressing the `cost` based on [**Gymnasium APIs**](https://github.com/Farama-Foundation/Gymnasium).\nThe `step` method returns 6 items `(next_obervation, reward, cost, terminated, truncated, info)` with an extra `cost` field.\n\n```python\nimport safety_gymnasium\n\nenv_id = 'SafetyPointGoal1-v0'\nenv = safety_gymnasium.make(env_id)\n\nobs, info = env.reset()\nwhile True:\n act = env.action_space.sample()\n obs, reward, cost, terminated, truncated, info = env.step(act)\n if terminated or truncated:\n break\n env.render()\n```\n\nWe also provide two convenience wrappers for converting the Safety-Gymnasium environment to the standard Gymnasium API and vice versa.\n\n```python\n# Safety-Gymnasium API: step returns (next_obervation, reward, cost, terminated, truncated, info)\n# Gymnasium API: step returns (next_obervation, reward, terminated, truncated, info) and cost is in the `info` dict associated with a str key `'cost'`\n\nsafety_gymnasium_env = safety_gymnasium.make(env_id)\ngymnasium_env = safety_gymnasium.wrappers.SafetyGymnasium2Gymnasium(safety_gymnasium_env)\n\nsafety_gymnasium_env = safety_gymnasium.wrappers.Gymnasium2SafetyGymnasium(gymnasium_env)\n```\n\nUsers can apply Gymnasium wrappers easily with:\n\n```python\nimport gymnasium\nimport safety_gymnasium\n\ndef make_safe_env(env_id):\n safe_env = safety_gymnasium.make(env_id)\n env = safety_gymnasium.wrappers.SafetyGymnasium2Gymnasium(safe_env)\n env = gymnasium.wrappers.SomeWrapper1(env)\n env = gymnasium.wrappers.SomeWrapper2(env, argname1=arg1, argname2=arg2)\n ...\n env = gymnasium.wrappers.SomeWrapperN(env)\n safe_env = safety_gymnasium.wrappers.Gymnasium2SafetyGymnasium(env)\n return safe_env\n```\n\nor\n\n```python\nimport functools\n\nimport gymnasium\nimport safety_gymnasium\n\ndef make_safe_env(env_id):\n return safety_gymnasium.wrappers.with_gymnasium_wrappers(\n safety_gymnasium.make(env_id),\n gymnasium.wrappers.SomeWrapper1,\n functools.partial(gymnasium.wrappers.SomeWrapper2, argname1=arg1, argname2=arg2),\n ...,\n gymnasium.wrappers.SomeWrapperN,\n )\n```\n\nIn addition, for all Safety-Gymnasium environments, we also provide corresponding Gymnasium environments with a suffix `Gymnasium` in the environment id. For example:\n\n```python\nimport gymnasium\nimport safety_gymnasium\n\nsafety_gymnasium.make('SafetyPointGoal1-v0') # step returns (next_obervation, reward, cost, terminated, truncated, info)\ngymnasium.make('SafetyPointGoal1Gymnasium-v0') # step returns (next_obervation, reward, terminated, truncated, info)\n```\n\n--------------------------------------------------------------------------------\n\n## Installation\n\n### Install from PyPI\n\n```bash\npip install safety-gymnasium\n```\n\n### Install from source\n\n```bash\nconda create -n <envname> python=3.8\nconda activate <envname>\n\ngit clone https://github.com/PKU-Alignment/safety-gymnasium.git\ncd safety-gymnasium\npip install -e .\n```\n\n### Important Notes\n\nIf you failed to render on your server, you can try:\n\n```bash\necho \"export MUJOCO_GL=osmesa\" >> ~/.bashrc\nsource ~/.bashrc\napt-get install libosmesa6-dev\napt-get install python3-opengl\n```\n\n--------------------------------------------------------------------------------\n\n## Customize your environments\n\nWe construct a highly expandable framework of code so that you can easily comprehend it and design your environments to facilitate your research with no more than 100 lines of code on average.\n\nFor details, please refer to our [documentation](https://www.safety-gymnasium.com/en/latest/components_of_environments/tasks/task_example.html).\nHere is a minimal example:\n\n```python\n# import the objects you want to use\n# or you can define specific objects by yourself, just make sure obeying our specification\nfrom safety_gymnasium.assets.geoms import Apples\nfrom safety_gymnasium.bases import BaseTask\n\n# inherit the basetask\nclass MytaskLevel0(BaseTask):\n def __init__(self, config):\n super().__init__(config=config)\n # define some properties\n self.num_steps = 500\n self.agent.placements = [(-0.8, -0.8, 0.8, 0.8)]\n self.agent.keepout = 0\n self.lidar_conf.max_dist = 6\n # add objects into environments\n self.add_geoms(Apples(num=2, size=0.3))\n\n def calculate_reward(self):\n # implement your reward function\n # Note: cost calculation is based on objects, so it's automatic\n reward = 1\n return reward\n\n def specific_reset(self):\n # depending on your task\n\n def specific_step(self):\n # depending on your task\n\n def update_world(self):\n # depending on your task\n\n @property\n def goal_achieved(self):\n # depending on your task\n```\n\n## Citing Safety-Gymnasium\n\nIf you find Safety-Gymnasium useful, please cite it in your publications.\n\n```bibtex\n@article{Safety-Gymnasium,\n author = {Jiaming Ji and Borong Zhang and Xuehai Pan and Jiayi Zhou and Juntao Dai and Yaodong Yang},\n title = {Safety-Gymnasium},\n year = {2023},\n publisher = {GitHub},\n journal = {GitHub repository},\n howpublished = {\\url{https://github.com/PKU-Alignment/safety-gymnasium}},\n}\n```\n\n## License\n\nSafety-Gymnasium is released under Apache License 2.0.\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "A highly scalable and customizable safe reinforcement learning environment.",
"version": "1.2.1",
"project_urls": {
"Bug Report": "https://github.com/PKU-Alignment/safety-gymnasium/issues",
"Documentation": "https://www.safety-gymnasium.com",
"Homepage": "https://github.com/PKU-Alignment/safety-gymnasium",
"Repository": "https://github.com/PKU-Alignment/safety-gymnasium"
},
"split_keywords": [
"safe reinforcement learning",
"rl environment",
"mujoco"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "aa4e5d45a62ac2d0aaf0e008f539db5180c36f5a9dc8d19b9d9e979bd2573c5d",
"md5": "872baea49cab550c39998600a50a3e32",
"sha256": "ed1a3dd874f75551e0a91fddf9e1399e44f93920b420fb48b0cae1c5b9cd33f5"
},
"downloads": -1,
"filename": "safety_gymnasium-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "872baea49cab550c39998600a50a3e32",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 72282198,
"upload_time": "2023-08-24T17:51:06",
"upload_time_iso_8601": "2023-08-24T17:51:06.096191Z",
"url": "https://files.pythonhosted.org/packages/aa/4e/5d45a62ac2d0aaf0e008f539db5180c36f5a9dc8d19b9d9e979bd2573c5d/safety_gymnasium-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "206a577167d6cc06d98861b4ce77f77256ef3194ab0c55bcbc8b4723a01ac62c",
"md5": "4cb83335a3111a669ff3eb3eb1d6e884",
"sha256": "805e698fd1480816556829ebe0edce7e54d4428c9198d4fca445aed49a8806f4"
},
"downloads": -1,
"filename": "safety-gymnasium-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "4cb83335a3111a669ff3eb3eb1d6e884",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 71872472,
"upload_time": "2023-08-24T17:51:39",
"upload_time_iso_8601": "2023-08-24T17:51:39.908328Z",
"url": "https://files.pythonhosted.org/packages/20/6a/577167d6cc06d98861b4ce77f77256ef3194ab0c55bcbc8b4723a01ac62c/safety-gymnasium-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-24 17:51:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PKU-Alignment",
"github_project": "safety-gymnasium",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "safety-gymnasium"
}
JSON
