<div align="center"> <h1> 安全体育馆 </h1> </div> <div align="center">

<a> Python 3.8+ </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> <a href="https://github.com/PKU-Alignment/safety-gymnasium#why-safety-gymnasium">为什么选择安全体育馆？</a> | <a href="https://www.safety-gymnasium.com">文档</a> | <a href="https://github.com/PKU-Alignment/safety-gymnasium#installation">安装指南</a> | <a href="https://github.com/PKU-Alignment/safety-gymnasium#customize-your-environments">自定义</a> | <a href="https://sites.google.com/view/safety-gymnasium">视频</a>

安全体育馆是一个高度可扩展和可定制的安全强化学习（SafeRL）库。它旨在提供一个良好的视角来对比SafeRL算法，并提供一套标准化的环境。我们提供了一组与约束信息兼容的标准API。用户可以通过优雅的代码框架和精心设计的环境探索新的见解。

引用安全体育馆

如果您发现安全体育馆对您有用，请在您的出版物中引用它。

@inproceedings{ji2023safety,
  title={Safety Gymnasium: 一个统一的安全强化学习基准},
  author={季家明 and 张博荣 and 周佳怡 and 潘雪海 and 黄伟东 and 孙瑞阳 and 耿一然 and 钟一帆 and 戴约瑟夫 and 杨耀东},
  booktitle={第三十七届神经信息处理系统会议数据集与基准跟踪},
  year={2023},
  url={https://openreview.net/forum?id=WZmlxIuIGR}
}

v1.1.0和v1.2.0版本注意事项❗️❗️❗️

我们已经更新了Safe Vision系列和Safe Isaac Gym系列的环境。但是，由于包大小限制，我们尚未将版本v1.1.0和v1.2.0上传到PyPI。因此，用户需要手动下载和安装。我们目前建议使用GitHub的Download zip功能来获取我们的包并访问最新环境。未来，我们计划将资源分别部署到云服务，以适应PyPI。请继续关注后续更新。

目前不支持Python 3.11，因为与pygame不兼容。

conda create -n example python=3.8
conda activate example
wget https://github.com/PKU-Alignment/safety-gymnasium/archive/refs/heads/main.zip
unzip main.zip
cd safety-gymnasium-main
pip install -e .

为什么选择Safety-Gymnasium?

这里我们提供了Safety-Gymnasium与现有SafeRL环境库的比较表格。

SafeRL<br/>环境	引擎	向量化<br/> 环境	新版Gym API<sup>(3)</sup>	视觉输入
Safety-Gym<br/>	`mujoco-py`<sup>(1)</sup>	❌	❌	最小程度支持
safe-control-gym<br/>	PyBullet	❌	❌	❌
速度约束<sup>(2)</sup>	不适用	❌	❌	❌
mujoco-circle<br/>	PyTorch	❌	❌	❌
Safety-Gymnasium<br/>	MuJoCo 2.3.0+	✅	✅	✅

(1): 维护（预期错误修复和小更新）；最后一次提交是2021年11月19日。Safety-Gym依赖于mujoco-py 2.0.2.7，该版本于2019年10月12日更新。 (2): 没有速度相关环境的官方库，其相关的成本约束是从信息中构建的。但该任务在SafeRL研究中广泛使用，我们在Safety-Gymnasium中对其进行了封装。 (3): 在gym 0.26.0版本更新中，重新定义了新的交互API。

环境

我们设计了各种安全增强学习任务，并整合了RL社区的贡献：safety-velocity、safety-run、safety-circle、safety-goal、safety-button等。我们引入了一个名为Safety-Gymnasium的统一安全增强学习基准环境库。

此外，为了促进社区研究的进展，我们重新设计了Safety-Gym并移除了对mujoco-py的依赖。我们在MuJoCo的基础上构建了它，并修复了一些错误，更具体的错误报告可以参考Safety-Gym的错误报告。

以下是我们目前支持的所有环境列表：

<table border="1"> <thead> <tr> <th>类别</th> <th>任务</th> <th>代理</th> <th>示例</th> </tr> </thead> <tbody> <tr> <td rowspan="4">安全导航</td> <td>按钮[012]</td> <td rowspan="4">点、汽车、四足机器人、赛车、蚂蚁</td> <td rowspan="4">SafetyPointGoal1-v0</td> </tr> <tr> <td>目标[012]</td> </tr> <tr> <td>推动[012]</td> </tr> <tr> <td>圆圈[012]</td> </tr> <tr> <td>安全速度</td> <td>速度</td> <td>半猎豹、跳跃者、游泳者、行走者2d、蚂蚁、人形机器人</td> <td>SafetyAntVelocity-v1</td> </tr> <tr> <td rowspan="7">安全视觉</td> <td>建筑按钮[012]</td> <td rowspan="7">点、汽车、四足机器人、赛车、蚂蚁</td> <td rowspan="7">SafetyFormulaOne1-v0</td> </tr> <tr> <td>建筑目标[012]</td> </tr> <tr> <td>建筑推动[012]</td> </tr> <tr> <td>简单淡出[012]</td> </tr> <tr> <td>困难淡出[012]</td> </tr> <tr> <td>赛车[012]</td> </tr> <tr> <td>一级方程式[012]</td> </tr> <tr> <td rowspan="8">安全多代理</td> <td>多目标[012]</td> <td>多点、多蚂蚁</td> <td>SafetyAntMultiGoal1-v0</td> </tr> <tr> <td>多代理速度</td> <td>6x1半猎豹、2x3半猎豹、3x1跳跃者、2x1游泳者、2x3行走者2d、2x4蚂蚁、4x2蚂蚁、9|8人形机器人</td> <td>Safety2x4AntVelocity-v0</td> </tr> <tr> <td>货运弗兰卡关闭抽屉（多代理）</td> <td rowspan="2">货运弗兰卡</td> <td rowspan="2">货运弗兰卡关闭抽屉（多代理）</td> </tr> <tr> <td>货运弗兰卡拾取和放置（多代理）</td> </tr> <tr> <td>影子手接球越过双臂下方安全手指（多代理）</td> <td rowspan="4">影子手</td> <td rowspan="4">影子手接球越过双臂下方安全关节（多代理）</td> </tr> <tr> <td>影子手接球越过双臂下方安全关节（多代理）</td> </tr> <tr> <td>影子手越过安全手指（多代理）</td> </tr> <tr> <td>影子手越过安全关节（多代理）</td> </tr> <tr> <td rowspan="6">安全Isaac健身房</td> <td>货运弗兰卡关闭抽屉</td> <td rowspan="2">货运弗兰卡</td> <td rowspan="2">货运弗兰卡关闭抽屉</td> </tr> <tr> <td>货运弗兰卡拾取和放置</td> </tr> <tr> <td>影子手接球越过双臂下方安全手指</td> <td rowspan="4">影子手</td> <td rowspan="4">影子手接球越过双臂下方安全关节</td> </tr> <tr> <td>影子手接球越过双臂下方安全关节</td> </tr> <tr> <td>影子手越过安全手指</td> </tr> <tr> <td>影子手越过安全关节</td> </tr> </tbody> </table>

以下是安全导航任务的一些截图。

代理

任务

基于视觉的安全强化学习

基于视觉的安全强化学习缺乏真实场景。尽管原始的Safety-Gym可以最低限度地支持视觉输入，但场景过于相似。为了便于验证基于视觉的安全强化学习算法，我们开发了一系列真实的基于视觉的安全强化学习任务，目前正在对基准进行验证。

作为开胃菜，图像如下所示：

环境使用

注意： 我们支持基于 Gymnasium APIs 明确表达 cost。 step 方法返回 6 个项目 (next_obervation, reward, cost, terminated, truncated, info)，其中包含一个额外的 cost 字段。

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()

我们还提供了两个便捷的包装器，用于将 Safety-Gymnasium 环境转换为标准 Gymnasium API，反之亦然。

# Safety-Gymnasium API: step 返回 (next_obervation, reward, cost, terminated, truncated, info)
# Gymnasium API:        step 返回 (next_obervation, reward, terminated, truncated, info)，cost 在 `info` 字典中与字符串键 `'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)

用户可以轻松应用 Gymnasium 包装器：

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

或者

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,
    )

此外，对于所有 Safety-Gymnasium 环境，我们还提供了相应的 Gymnasium 环境，环境 ID 后缀为 Gymnasium。例如：

import gymnasium
import safety_gymnasium

safety_gymnasium.make('SafetyPointGoal1-v0')    # step 返回 (next_obervation, reward, cost, terminated, truncated, info)
gymnasium.make('SafetyPointGoal1Gymnasium-v0')  # step 返回 (next_obervation, reward, terminated, truncated, info)

安装

从 PyPI 安装

pip install safety-gymnasium

从源代码安装

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 .

重要说明

如果在服务器上无法渲染，可以尝试：

echo "export MUJOCO_GL=osmesa" >> ~/.bashrc
source ~/.bashrc
apt-get install libosmesa6-dev
apt-get install python3-opengl

使用键盘进行调试

对于简单的智能体，我们提供了通过键盘控制机器人移动的功能，便于调试。只需在任务名称后添加 Debug 后缀，例如 SafetyCarGoal2Debug-v0，然后使用 I、K、J 和 L 键来引导机器人的移动。对于更复杂的代理，您还可以根据特定外设制定自定义控制逻辑。为了实现这一点，请为指定的代理实现BaseAgent中的debug方法。

自定义您的环境

我们构建了一个高度可扩展的代码框架，使您能够轻松理解并设计自己的环境，以便于您的研究，平均只需不到100行代码。

详情请参阅我们的文档。以下是一个最小示例：

# 导入您想使用的对象
# 或者您可以自己定义特定对象，只需确保遵守我们的规范
from safety_gymnasium.assets.geoms import Apples
from safety_gymnasium.bases import BaseTask

# 继承BaseTask
class MytaskLevel0(BaseTask):
    def __init__(self, config):
        super().__init__(config=config)
        # 定义一些属性
        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
        # 向环境中添加对象
        self.add_geoms(Apples(num=2, size=0.3))

    def calculate_reward(self):
        # 实现您的奖励函数
        # 注意：成本计算基于对象，因此是自动的
        reward = 1
        return reward

    def specific_reset(self):
        # 根据您的任务而定

    def specific_step(self):
        # 根据您的任务而定

    def update_world(self):
        # 根据您的任务而定

    @property
    def goal_achieved(self):
        # 根据您的任务而定