Gymnasium 发布说明

v1.1.0

发布于 2025-02-26 - GitHub - PyPI

Gymnasium v1.1

在此版本中，我们修复了 Gymnasium v1.0 的几个错误，并添加了新功能以改进所做的更改。

随着 Gymnasium v1.0 的发布，我们所做的主要更改之一是向量环境的实现，改进了用户与其交互和扩展它的方式。一些用户指出，他们需要与向量环境自动重置子环境（当子环境终止或截断时）的方式向后兼容，这被称为自动重置模式或 API。因此，在 v1.1 中，我们为已实现的向量环境（SyncVectorEnv 和 AsyncVectorEnv）和所有三种可能模式的封装器添加了支持：next-step、same-step 和 disabled。要了解使用的自动重置模式类型，应在向量环境元数据 metadata["autoreset_mode"] 中指定为 gymnasium.vectors.AutoresetMode 枚举。有关自动重置模式之间差异以及如何使用它们的更多信息，请阅读 https://farama.org/Vector-Autoreset-Mode。

此外，我们还添加了几个有用的功能

  • 在 Gymnasium v0.25 中，我们为 spaces（空间）添加了掩码，space.sample(mask=...)，以逻辑地屏蔽掉 spaces（空间）中可能的样本。#1310 为每个 space（空间）添加了概率掩码 space.sample(probability=...) 以指定每个样本的概率，这对于输出动作概率分布的 RL 策略很有帮助。
  • 对于 MuJoCo 环境，用户可以选择使用 RGB 图像或基于深度的图像来渲染机器人。以前，只能访问 RGB 或深度渲染。Gymnasium v1.1 添加了 RGBD 渲染，将 RGB 和基于深度的图像作为单个输出输出。
  • 在 Gymnasium v1.0 中，我们改进了 jax、torch 和 numpy 之间转换的封装器，包括 JaxToTorch、JaxToNumpy、NumpyToTorch 等。在 v1.1 中，我们改进了封装器以支持渲染并与完整的 dlpack API 兼容。

新功能

  • 通过 @mariojerez 添加了具有概率掩码的 Space（空间）采样 (#1310)
  • 通过 @DavidPL1 向 mujoco 添加 rgb + 深度渲染 (#1229)
  • 通过 @amacati 为 JaxToNumpy、JaxToTorch 和 NumpyToTorch 添加渲染支持 (#1306)
  • 通过 @amacati 添加对 dlpack API 的完整支持 (#1299)
  • 通过 @sparisi 启用 StickyAction 封装器以将旧动作重复超过 1 步 (#1240)
  • 通过 @howardh 为单个 obs/action space（观测/动作空间）参数添加 wrappers.vector.TransformObs/Action 支持 (#1288)
  • 通过 @duburcqa 改进 wrappers（封装器）的 'set_wrapper_attr' 以修改变量的更新方式 (#1294)
  • 通过 @li-plus 允许 AtariPreprocessing 支持非正方形观测 (#1312)
  • 通过 @pseudo-rnd-thoughts 改进 Wrapper 和 VectorWrapper 错误检查 (#1260)

Bug Fixes（Bug 修复）

Documentation Changes（文档变更）

  • 由 @artemmiyy 修复了 blackjack（二十一点）中采样值的拼写错误，应为 2-10 而不是 2-9 (#1250)
  • 由 @godsboy404 添加了一些流行的第三方初学者教程 (#1271)
  • 由 @keraJLi 更新了奖励缩放封装器的文档 (#1285)

感谢 31 位新贡献者为此版本做出的贡献，完整变更日志： v1.0.0...v1.1.0

v1.0.0

发布于 2024-10-08 - GitHub - PyPI

v1.0.0 发布说明

在过去的几年里，Gym 和 Gymnasium 背后的志愿者团队致力于修复错误、改进文档、添加新功能，并在适当的时候更改 API，以使收益超过成本。这是 v1.0.0 的完整版本，这将是更改项目中心 API（Env、Space、VectorEnv）之路的终点。此外，自 0.29.1 以来，此版本已包含 200 多个 PR，其中包含许多错误修复、新功能和改进的文档。因此，感谢所有志愿者为此付出的辛勤工作，使之成为可能。在这些发布说明的其余部分，我们包含了核心 API 更改的部分，最后是包含的其他新功能、错误修复、弃用和文档更改。

最后，我们发表了一篇关于 Gymnasium 的论文，讨论了其总体设计决策等，网址为 https://arxiv.org/abs/2407.17032，可以使用以下方式引用

@misc{towers2024gymnasium,
      title={Gymnasium: A Standard Interface for Reinforcement Learning Environments}, 
      author={Mark Towers and Ariel Kwiatkowski and Jordan Terry and John U. Balis and Gianluca De Cola and Tristan Deleu and Manuel Goulão and Andreas Kallinteris and Markus Krimmel and Arjun KG and Rodrigo Perez-Vicente and Andrea Pierré and Sander Schulhoff and Jun Jet Tai and Hannah Tan and Omar G. Younis},
      year={2024},
      eprint={2407.17032},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2407.17032}, 
}

移除插件系统

在 Gym v0.23+ 和 Gymnasium v0.26 到 v0.29 中，已删除在幕后注册外部环境的未记录功能。对于 Atari (ALE)、Minigrid 或 HighwayEnv 的用户，则用户以前可以使用以下代码

import gymnasium as gym

env = gym.make("ALE/Pong-v5")

尽管从未导入 Atari（即，import ale_py），用户仍然可以创建 Atari 环境。此功能已在 v1.0.0 中删除，这将要求用户更新为

import gymnasium as gym
import ale_py

gym.register_envs(ale_py)  # optional, helpful for IDEs or pre-commit

env = gym.make("ALE/Pong-v5")

或者，用户可以使用以下结构，module_name:env_id，以便在创建环境之前首先导入模块。例如，ale_py:ALE/Pong-v5。

import gymnasium as gym

env = gym.make("ale_py:ALE/Pong-v5")

为了帮助用户使用 IDE（例如，VSCode、PyCharm），当导入模块以注册环境时（例如，import ale_py），这可能会导致 IDE（和 pre-commit isort / black / flake8）认为导入是毫无意义的，应该删除。因此，我们引入了 gymnasium.register_envs 作为无操作函数（该函数实际上什么也不做），以使 IDE 相信正在发生某些事情并且需要 import 语句。

向量环境

为了提高环境的采样速度，向量化是同时采样同一环境的多个实例的最简单方法之一。Gym 和 Gymnasium 提供了 VectorEnv 作为此操作的基类，但其问题之一是它继承了 Env。这可能会导致类型检查（Env 和 VectorEnv 的 step 返回类型不同）、测试环境类型（isinstance(env, Env) 对于向量环境可能为真，尽管两者的行为不同）以及最终的 wrappers（封装器）（一些 Gym 和 Gymnasium wrappers（封装器）支持向量环境，但没有明确或一致的 API 来确定哪些支持或不支持）。因此，我们已将 Env 和 VectorEnv 分开，不再相互继承。

在实现新的独立 VectorEnv 类时，我们尝试最大限度地减少使用 Env 和 VectorEnv 的代码之间的差异，并使其在某些地方更通用。该类包含与 Env 相同的属性和方法，此外还包含属性 num_envs: int、single_action_space: gymnasium.Space 和 single_observation_space: gymnasium.Space。此外，我们从 VectorEnv 中删除了几个并非所有向量实现都需要的函数：step_async、step_wait、reset_async、reset_wait、call_async 和 call_wait。此更改现在允许用户编写自己的自定义向量环境，v1.0.0 包括一个示例向量 Cartpole 环境，该环境仅使用 NumPy 编写，比使用 Gymnasium 的 Sync 向量环境快数千倍。

为了方便用户轻松创建向量化环境，我们提供了 gymnasium.make_vec 作为 gymnasium.make 的向量化等效项。由于有多种不同的向量化选项（“sync”、“async”和一个称为“vector_entry_point”的自定义类），因此参数 vectorization_mode 选择环境的向量化方式。此参数默认为 None，这样，如果环境具有自定义向量环境实现的向量入口点，则将首先使用该入口点（目前，Cartpole 是唯一一个在 Gymnasium 中内置向量入口点的环境）。否则，将使用同步向量化器（以前，Gym 和 Gymnasium vector.make 默认使用异步向量化器）。有关更多信息，请参阅函数 docstring。我们很高兴看到其他项目利用此选项来更轻松地创建他们的环境。

env = gym.make("CartPole-v1")
env = gym.wrappers.ClipReward(env, min_reward=-1, max_reward=3)

envs = gym.make_vec("CartPole-v1", num_envs=3)
envs = gym.wrappers.vector.ClipReward(envs, min_reward=-1, max_reward=3)

由于 Env 和 VectorEnv 的这种分离，现在 gymnasium.wrappers 中只有 Env 封装器，gymnasium.wrappers.vector 中只有 VectorEnv 封装器。此外，我们将基本向量封装器的名称从 VectorEnvWrapper 更新为 VectorWrapper，并添加了 VectorObservationWrapper、VectorRewardWrapper 和 VectorActionWrapper 类。有关新信息，请参阅 vector wrapper 页面。

为了提高向量环境的效率，自动重置是一项常见功能，允许子环境在无需所有子环境完成之前重置所有子环境的情况下进行重置。以前在 Gym 和 Gymnasium 中，自动重置是在环境 episode（回合）结束的同一步骤中完成的，这样，最终的观测和信息将存储在步骤的信息中，即 info["final_observation"] 和 info[“final_info”]，以及包含子环境重置观测和信息的标准 obs 和 info。因此，从向量环境准确采样观测需要以下代码（注意，如果子环境终止或截断，则需要提取 infos["next_obs"][j]）。此外，对于使用 rollout 的 on-policy 算法，将需要额外的正向传递来计算正确的下一个观测（这通常不作为优化来完成，假设环境仅终止，而不截断）。

replay_buffer = []
obs, _ = envs.reset()
for _ in range(total_timesteps):
    next_obs, rewards, terminations, truncations, infos = envs.step(envs.action_space.sample())

    for j in range(envs.num_envs):
        if not (terminations[j] or truncations[j]):
            replay_buffer.append((
                obs[j], rewards[j], terminations[j], truncations[j], next_obs[j]
            ))
        else:
            replay_buffer.append((
                obs[j], rewards[j], terminations[j], truncations[j], infos["next_obs"][j]
            ))

    obs = next_obs

然而，随着时间的推移，开发团队认识到这种方法的效率低下（主要是由于 Python 字典的广泛使用）以及必须提取最终观测才能正确训练智能体的烦恼，例如 example。因此，在 v1.0.0 中，我们正在修改自动重置以与专门的仅向量项目（如 EnvPool 和 SampleFactory）保持一致，在这些项目中，子环境在下一步之前不会重置。因此，采样时需要进行以下更改

replay_buffer = []
obs, _ = envs.reset()
autoreset = np.zeros(envs.num_envs)
for _ in range(total_timesteps):
    next_obs, rewards, terminations, truncations, _ = envs.step(envs.action_space.sample())

    for j in range(envs.num_envs):
        if not autoreset[j]:
            replay_buffer.append((
                obs[j], rewards[j], terminations[j], truncations[j], next_obs[j]
            ))

    obs = next_obs
    autoreset = np.logical_or(terminations, truncations)

对于 on-policy rollout，为了考虑自动重置，需要屏蔽新 episode（回合）中第一个观测的误差 (done[t+1])，以防止计算 episode（回合）的最后一个和第一个观测之间的误差。

最后，我们改进了 AsyncVectorEnv.set_attr 和 SyncVectorEnv.set_attr 函数以使用 Wrapper.set_wrapper_attr，从而允许用户在环境堆栈中的任何位置设置变量（如果该变量已存在）。以前，这是不可能的，用户只能修改环境堆栈中“顶部”封装器中的变量，重要的是不能修改实际环境本身。

Wrappers（封装器）

以前，某些封装器可以同时支持环境和向量环境，但是，这并未标准化，并且不清楚哪些封装器支持和不支持向量环境。对于 v1.0.0，由于 Env 和 VectorEnv 分开，不再相互继承（在向量部分阅读更多内容），gymnasium.wrappers 中的封装器将仅支持标准环境，而 gymnasium.wrappers.vector 包含提供的专用向量封装器（支持大多数但并非所有封装器，如果您需要它，请提出功能请求）。

在 v0.29 中，我们弃用了 Wrapper.__getattr__ 函数，并将其替换为 Wrapper.get_wrapper_attr，从而提供对环境堆栈中任何位置的变量的访问权限。在 v1.0.0 中，我们添加了 Wrapper.set_wrapper_attr 作为等效函数，用于在环境堆栈中的任何位置设置变量（如果该变量已存在）；否则，该变量将分配给顶部封装器。

最重要的是，我们删除、重命名和添加了以下几个封装器。

  • 已删除的封装器
    • monitoring.VideoRecorder - 替换封装器为 RecordVideo
    • StepAPICompatibility - 我们希望所有 Gymnasium 环境都使用 terminated（终止）/ truncated（截断）步骤 API，因此，用户不应需要 StepAPICompatibility 封装器。Shimmy 包括一个兼容性环境，用于将 gym-api 环境转换为 gymnasium。
  • 重命名的封装器（我们希望使封装器的命名保持一致。因此，我们已从所有封装器中删除了“Wrapper”，并在适当的情况下在封装器名称中包含“Observation”、“Action”和“Reward”）
    • AutoResetWrapper -> Autoreset
    • FrameStack -> FrameStackObservation
    • PixelObservationWrapper -> AddRenderObservation
  • 移动的封装器（所有向量封装器都在 gymnasium.wrappers.vector 中）
    • VectorListInfo -> vector.DictInfoToList
  • 添加的封装器
    • DelayObservation - 为下一个观测和奖励添加延迟
    • DtypeObservation - 修改环境观测空间的数据类型
    • MaxAndSkipObservation - 将跳过 n 个观测值，并将最后 2 个观测值取最大值，灵感来自 Atari 环境针对其他环境的启发式方法
    • StickyAction - 以概率随机重复动作，以进行一步，返回最终观测值和步骤的奖励总和。灵感来自 Atari 环境启发式方法
    • JaxToNumpy - 将基于 Jax 的环境转换为使用基于 Numpy 的输入和输出数据进行 reset、step 等操作
    • JaxToTorch - 将基于 Jax 的环境转换为使用基于 PyTorch 的输入和输出数据进行 reset、step 等操作
    • NumpyToTorch - 将基于 Numpy 的环境转换为使用基于 PyTorch 的输入和输出数据进行 reset、step 等操作

对于所有封装器，我们都添加了示例代码文档和变更日志，以帮助未来的研究人员了解所做的任何更改。请参阅以下 page 以获取示例。

函数式环境

Gymnasium 的 Env 的主要优势之一是它通常只需要关于底层环境规范的极少信息；但是，这可能会使将此类环境应用于规划、搜索算法和理论研究变得更加困难。我们建议使用 FuncEnv 作为 Env 的替代定义，它更接近马尔可夫决策过程定义，向用户公开更多函数，包括观测、奖励和终止函数以及环境的原始状态作为单个对象。

from typing import Any
import gymnasium as gym
from gymnasium.functional import StateType, ObsType, ActType, RewardType, TerminalType, Params

class ExampleFuncEnv(gym.functional.FuncEnv):
  def initial(self, rng: Any, params: Params | None = None) -> StateType:
    ...
  def transition(self, state: StateType, action: ActType, rng: Any, params: Params | None = None) -> StateType:
    ...
  def observation(self, state: StateType, rng: Any, params: Params | None = None) -> ObsType:
    ...
  def reward(
      self, state: StateType, action: ActType, next_state: StateType, rng: Any, params: Params | None = None
  ) -> RewardType:
    ...
  def terminal(self, state: StateType, rng: Any, params: Params | None = None) -> TerminalType:
    ...

FuncEnv 要求 initial 和 transition 函数返回一个新状态（给定其输入），作为 Env.step 和 Env.reset 的部分实现。因此，用户可以采样（和保存）一系列输入的下一个状态，以用于规划、搜索等。给定一个状态，observation、reward 和 terminal 为用户提供了明确的定义，以了解每个定义如何影响环境的输出。

收集种子值

可以使用 None 为环境和 space（空间）播种以使用随机初始种子值，但是不可能知道这些初始种子值是什么。我们已在 #1033 和 #889 中解决了 Space.seed 和 reset.seed 的问题。此外，对于 Space.seed，我们已将返回类型更改为针对每个 space（空间）进行专门化，以便以下代码适用于所有 space（空间）。

seeded_values = space.seed(None)
initial_samples = [space.sample() for _ in range(10)]

reseed_values = space.seed(seeded_values)
reseed_samples = [space.sample() for _ in range(10)]

assert seeded_values == reseed_values
assert initial_samples == reseed_samples

此外，对于环境，我们添加了一个新的 np_random_seed 属性，该属性将存储来自 reset(seed=seed) 的最新 np_random 种子值。

环境版本变更

  • 最近发现，基于 MuJoCo 的 Pusher 与 mujoco>= 3 不兼容，因为智能体必须推动的方块的模型密度比空气轻。这显然开始给使用 mujoco>= 3 和 Pusher 的用户带来问题。因此，我们禁用了 mujoco>= 3 的 v4 环境，并更新为 MuJoCo v5 中的模型，该模型产生更预期的行为，如 v4 和 mujoco< 3 (#1019)。

  • 新的 v5 MuJoCo 环境作为两年前添加的 v4 环境的后续，修复了一致性问题，添加了新功能并更新了文档 (#572)。此外，我们已决定将基于 mujoco-py 的（v2 和 v3）环境标记为已弃用，并计划在未来将其从 Gymnasium 中删除 (#926)。

  • Lunar Lander 版本从 v2 增加到 v3，原因是两个 bug 修复。第一个修复了环境的确定性，使得世界对象在重置时未完全销毁，从而在特定情况下导致不确定性 (#979)。其次，风力生成（默认情况下已关闭）不是由每次重置随机生成的，因此，我们已更新此设置以获得 episode（回合）之间的统计独立性 (#959)。

  • CarRacing 版本从 v2 增加到 v3，以更改环境结束的方式，以便当智能体完成赛道时，环境将 terminate（终止）而不是 truncate（截断）。

  • 我们已删除 pip install "gymnasium[accept-rom-license]"，因为 ale-py>=0.9 现在随 roms 一起打包，这意味着用户不再需要使用 autoroms 单独安装 atari roms。

其他 Bug 修复

  • spaces.Box 允许低值和高值超出数据类型的范围，这可能会导致一些非常奇怪的边缘情况，这些情况非常难以检测，由 @pseudo-rnd-thoughts 修复 (#774)
  • 由 @pseudo-rnd-thoughts 修复了由于 cython==3 问题而限制 gymnasium[mujoco-py] 的 cython 版本的问题 (#616)
  • 由 @logan-dunbar 修复了具有自定义宽度值的 mujoco 渲染问题 (#634)
  • 修复环境检查器，以正确报告无限边界，由 @chrisyeh96 (#708)
  • 修复 register(kwargs) 的类型提示，从 **kwargs 更改为 kwargs: dict | None = None，由 @younik (#788)
  • 修复 AsyncVectorEnv 中自定义环境的注册问题，由 @RedTachyon (#810)
  • 移除 v4+ MuJoCo 环境的 mujoco-py 导入错误，由 @MischaPanch
    (#934)
  • 修复读取 Tuple 和 Dict 空间的共享内存问题 (#941)
  • 修复 Windows 上 Multidiscrete.from_jsonable 的问题 (#932)
  • 移除 play 渲染归一化 (#956)
  • 修复 to_torch 转换中未使用的 device 参数，由 @mantasu (#1107)
  • 修复在 GPU 上时 torch 到 numpy 的转换问题，由 @mantasu (#1109)

其他新功能

弃用

文档变更

完整变更日志: v0.29.1...v1.0.0

v1.0.0a2: v1.0.0 alpha 2

发布于 2024-05-21 - GitHub - PyPI

这是我们的第二个 alpha 版本，我们希望这是 Gymnasium v1.0.0 正式发布前的最后一个版本。我们总结了此 alpha 版本中添加的关键更改、错误修复和新功能。

主要变更

Atari 环境

提供 Atari 环境的 ale-py 已在 v0.9.0 中更新，以使用 Gymnasium 作为 API 后端。此外，pip 安装包包含 ROM，因此安装 Atari 所需的全部操作应该是 pip install “gymnasium[atari]”（因此，gymnasium[accept-rom-license] 已被移除）。提醒一下，对于 Gymnasium v1.0 注册外部环境（例如，ale-py），您需要在创建任何 Atari 环境之前 import ale_py。

收集种子值

可以使用 None 同时为环境和空间播种以使用随机初始种子值，但是不可能知道这些初始种子值是什么。我们在 #1033 和 #889 中解决了 Space.seed 和 reset.seed 的这个问题。对于 Space.seed，我们已将返回类型更改为针对每个空间进行专门化，以便以下代码适用于所有空间。

seeded_values = space.seed(None)
initial_samples = [space.sample() for _ in range(10)]

reseed_values = space.seed(seeded_values)
reseed_samples = [space.sample() for _ in range(10)]

assert seeded_values == reseed_values
assert initial_samples == reseed_samples

此外，对于环境，我们添加了一个新的 np_random_seed 属性，该属性将存储来自 reset(seed=seed) 的最新 np_random 种子值。

环境版本变更

  • 最近发现，由于错误修复，基于 mujoco 的 pusher 与 MuJoCo >= 3 不兼容，这些错误修复发现代理必须推动的块的模型密度是空气的密度。这显然开始为使用 MuJoCo v3+ 和 Pusher 的用户带来问题。因此，我们禁用了 MuJoCo >= 3 的 v4 环境，并更新为 MuJoCo v5 中的模型，该模型产生更符合预期的行为，如 v4 和 MuJoCo < 3 (#1019)。
  • Alpha 2 包括新的 v5 MuJoCo 环境，作为两年前添加的 v4 环境的后续，修复了一致性问题，添加了新功能并更新了文档。我们已决定将 MuJoCo-py (v2 和 v3) 环境标记为已弃用，并计划在未来从 Gymnasium 中移除它们 (#926)。
  • Lunar Lander 版本从 v2 增加到 v3，原因是两个 bug 修复。第一个修复了环境的确定性，使得世界对象在重置时未完全销毁，从而在特定情况下导致不确定性 (#979)。其次，风力生成（默认情况下已关闭）不是由每次重置随机生成的，因此，我们已更新此设置以获得 episode（回合）之间的统计独立性 (#959)。

Box 示例

发现 spaces.Box 允许低值和高值超出 dtype 的范围 (#774)，这可能会导致一些非常奇怪的边缘情况，这些情况很难检测。我们希望这些更改可以改进调试和检测空间的无效输入，但是，如果您的环境引发与此相关的问题，请告知我们。

Bug Fixes（Bug 修复）

  • 为新的 autoreset API 更新了 CartPoleVectorEnv (#915)
  • 从新的 autoreset api 修复了 wrappers.vector.RecordEpisodeStatistics 的 episode length 计算 (#1018)
  • 移除 v4+ MuJoCo 环境的 mujoco-py 导入错误 (#934)
  • 修复了 make_vec(**kwargs) 未传递到向量入口点 envs 的问题 (#952)
  • 修复读取 Tuple 和 Dict 空间的共享内存问题 (#941)
  • 修复了 Windows 上的 Multidiscrete.from_jsonable 问题 (#932)
  • 移除了 play 渲染归一化 (#956)

新功能

  • 添加了 Python 3.12 支持
  • 添加了一个新的 OneOf 空间，该空间提供空间的互斥联合 (#812)
  • 由于放弃了 Python 3.7 支持，更新了 Dict.sample 以使用标准 Python 字典而不是 OrderedDict (#977)
  • Jax 环境返回 jax 数据而不是 numpy 数据 (#817)
  • 添加了 wrappers.vector.HumanRendering 并从 CartPoleVectorEnv 中移除了人工渲染 (#1013)
  • 在用户混合使用 Gym 和 Gymnasium 时添加了更有帮助的错误消息 (#957)
  • 为 CartPole 添加了 sutton_barto_reward 参数，该参数更改奖励函数，使其在终止状态下不返回 1 (#958)
  • 为 MuJoCo 环境添加了 visual_options 渲染参数 (#965)
  • 为 utlis.env_checker.data_equivilance 添加了 exact 参数 (#924)
  • 更新了 wrapper.NormalizeObservation 观察空间，并将观察更改为 float32 (#978)
  • 捕获了 env.spec 期间的异常（如果 kwarg 不可 pickle） (#982)
  • 改进了 Box2D 的 ImportError (#1009)
  • 为 VectorEnv 和 VectorWrapper 添加了元数据字段 (#1006)
  • 修复了修改 make 参数时同步或异步的 make_vec 问题 (#1027)

完整变更日志: v1.0.0a1...v1.0.0a2 v0.29.1...v1.0.0a2

v1.0.0a1: v1.0.0 alpha1

发布于 2024-02-13 - GitHub - PyPI

在过去的几年里，Gym 和 Gymnasium 背后的志愿者团队致力于修复错误、改进文档、添加新功能以及在适当的时候更改 API，以使收益大于成本。这是 v1.0.0 的第一个 alpha 版本，旨在结束项目 API 更改之路，并包含许多新功能和改进的文档。

要安装 v1.0.0a1，您必须使用 pip install gymnasium==1.0.0a1 或 pip install --pre gymnasium，否则将安装 v0.29.1。同样，网站将默认显示 v0.29.1 的文档，您可以使用右下角的弹出窗口进行更改。

我们非常希望项目能够使用这些 v1.0.0 alpha 版本进行测试，以便在我们完全发布 v1.0 之前找到任何错误、文档缺失或 API 更改问题。

移除插件系统

在 Gym v0.23+ 和 Gymnasium v0.26 到 v0.29 中，一个未记录的功能（用于在后台注册外部环境）已被移除。对于 Atari (ALE)、Minigrid 或 HighwayEnv 的用户，则可以使用以下代码

import gymnasium as gym

env = gym.make("ALE/Pong-v5")

这样，即使从未导入 Atari（即 import ale_py），用户仍然可以加载 Atari 环境。此功能已在 v1.0.0 中移除，这将要求用户更新为

import gymnasium as gym
import ale_py

gym.register_envs(ale_py)  # optional

env = gym.make("ALE/Pong-v5")

或者，用户可以执行以下操作，其中环境 ID 中的 ale_py 将导入模块

import gymnasium as gym

env = gym.make("ale_py:ALE/Pong-v5")  # `module_name:env_id`

对于使用 IDE（即 VSCode、PyCharm）的用户，import ale_py 可能会导致 IDE（以及 pre-commit isort / black / flake8）认为 import 语句没有任何作用。因此，我们引入了 gymnasium.register_envs 作为一个空操作函数（该函数实际上什么也不做），以使 IDE 相信正在发生某些事情，并且需要 import 语句。

注意：ALE-py、Minigrid 和 HighwayEnv 必须更新才能与 Gymnasium v1.0.0 一起使用，我们希望为所有受 alpha 2 影响的项目完成更新。

向量环境

为了提高环境的采样速度，向量化是同时采样同一环境的多个实例的最简单方法之一。Gym 和 Gymnasium 提供了 VectorEnv 作为此操作的基类，但它的问题之一是它继承了 Env。这可能会导致类型检查方面出现特殊问题（Env 和 VectorEnv 的 step 返回类型不同）、环境类型测试（对于向量环境，isinstance(env, Env) 可能为真，尽管两者的行为不同）以及包装器（一些 Gym 和 Gymnasium 包装器支持向量环境，但没有明确或一致的 API 来确定哪些支持或不支持）。因此，我们已将 Env 和 VectorEnv 分开，使其彼此不继承。

在实现新的独立 VectorEnv 类时，我们已尝试最大限度地减少使用 Env 和 VectorEnv 的代码之间的差异，并使其在某些方面更通用。该类包含与 Env 相同的属性和方法，以及 num_envs: int、single_action_space: gymnasium.Space 和 single_observation_space: gymnasium.Space。此外，我们还从 VectorEnv 中移除了几个并非所有向量实现都需要的函数：step_async、step_wait、reset_async、reset_wait、call_async 和 call_wait。此更改现在允许用户编写自己的自定义向量环境，v1.0.0a1 包括一个示例向量 Cartpole 环境，其运行速度比使用 Gymnasium 的同步向量环境快数千倍。

为了方便用户轻松创建向量化环境，我们提供了 gymnasium.make_vec 作为 gymnasium.make 的向量化等效项。由于有多种不同的向量化选项（“sync”、“async”和一个称为“vector_entry_point”的自定义类），参数 vectorization_mode 选择环境的向量化方式。此参数默认为 None，这样，如果环境具有自定义向量环境实现的向量入口点，则将首先使用该入口点（目前，Cartpole 是唯一在 Gymnasium 中内置了向量入口点的环境）。否则，将使用同步向量化器（以前，Gym 和 Gymnasium vector.make 默认使用异步向量化器）。有关更多信息，请参阅函数 文档字符串。

​​env = gym.make("CartPole-v1")
env = gym.wrappers.ClipReward(env, min_reward=-1, max_reward=3)

envs = gym.make_vec("CartPole-v1", num_envs=3)
envs = gym.wrappers.vector.ClipReward(envs, min_reward=-1, max_reward=3)

由于 Env 和 VectorEnv 的这种分离，现在 gymnasium.wrappers 中只有 Env 封装器，gymnasium.wrappers.vector 中只有 VectorEnv 封装器。此外，我们将基本向量封装器的名称从 VectorEnvWrapper 更新为 VectorWrapper，并添加了 VectorObservationWrapper、VectorRewardWrapper 和 VectorActionWrapper 类。有关新信息，请参阅 vector wrapper 页面。

为了提高向量环境的效率，自动重置是一项常用功能，它允许子环境在所有子环境完成之前重置它们。以前在 Gym 和 Gymnasium 中，自动重置是在环境 episode 结束的同一步骤中完成的，这样，最终的观察和信息将存储在步骤的信息中，即 info["final_observation"] 和 info[“final_info”]，标准 obs 和 info 包含子环境的重置观察和信息。这需要类似的向量化环境的通用采样。

replay_buffer = []
obs, _ = envs.reset()
for _ in range(total_timesteps):
    next_obs, rewards, terminations, truncations, infos = envs.step(envs.action_space.sample())

    for j in range(envs.num_envs):
        if not (terminations[j] or truncations[j]):
            replay_buffer.append((
                obs[j], rewards[j], terminations[j], truncations[j], next_obs[j]
            ))
        else:
            replay_buffer.append((
                obs[j], rewards[j], terminations[j], truncations[j], infos["next_obs"][j]
            ))

    obs = next_obs

然而，随着时间的推移，开发团队已经认识到这种方法的低效率（主要是由于 Python 字典的广泛使用）以及必须提取最终观察结果才能正确训练 agent 的麻烦，例如 示例。因此，在 v1.0.0 中，我们正在修改自动重置以与专门的仅向量项目（如 EnvPool 和 SampleFactory）保持一致，这样，子环境在下一步之前不会重置。因此，这需要在采样时进行以下更改。对于具有更复杂的观察空间（和动作动作）的环境，则

replay_buffer = []
obs, _ = envs.reset()
autoreset = np.zeros(envs.num_envs)
for _ in range(total_timesteps):
    next_obs, rewards, terminations, truncations, _ = envs.step(envs.action_space.sample())

    for j in range(envs.num_envs):
        if not autoreset[j]:
            replay_buffer.append((
                obs[j], rewards[j], terminations[j], truncations[j], next_obs[j]
            ))

    obs = next_obs
    autoreset = np.logical_or(terminations, truncations)

最后，我们改进了 AsyncVectorEnv.set_attr 和 SyncVectorEnv.set_attr 函数，以使用 Wrapper.set_wrapper_attr，允许用户在环境堆栈中已存在的任何位置设置变量。以前，这是不可能的，用户只能修改环境堆栈“顶部”包装器中的变量，重要的是不能修改环境本身。

Wrappers（封装器）

以前，某些封装器可以同时支持环境和向量环境，但是，这并未标准化，并且不清楚哪些封装器支持和不支持向量环境。对于 v1.0.0，由于 Env 和 VectorEnv 分开，不再相互继承（在向量部分阅读更多内容），gymnasium.wrappers 中的封装器将仅支持标准环境，而 gymnasium.wrappers.vector 包含提供的专用向量封装器（支持大多数但并非所有封装器，如果您需要它，请提出功能请求）。

在 v0.29 中，我们弃用了 Wrapper.__getattr__ 函数，并将其替换为 Wrapper.get_wrapper_attr，从而可以访问环境堆栈中任何位置的变量。在 v1.0.0 中，我们添加了 Wrapper.set_wrapper_attr 作为等效函数，用于在环境堆栈中已存在的任何位置设置变量；仅在顶部包装器（或环境）中设置变量。

最重要的是，我们删除、重命名和添加了以下几个封装器。

  • 已删除的封装器
    • monitoring.VideoRecorder - 替换封装器为 RecordVideo
    • StepAPICompatibility - 我们希望所有 Gymnasium 环境都使用 terminated / truncated 步骤 API，因此，用户不应需要 StepAPICompatibility 包装器。Shimmy 包含一个兼容性环境，用于转换 gym-api 环境以用于 gymnasium。
  • 重命名的封装器（我们希望使封装器的命名保持一致。因此，我们已从所有封装器中删除了“Wrapper”，并在适当的情况下在封装器名称中包含“Observation”、“Action”和“Reward”）
    • AutoResetWrapper -> Autoreset
    • FrameStack -> FrameStackObservation
    • PixelObservationWrapper -> AddRenderObservation
  • 移动的封装器（所有向量封装器都在 gymnasium.wrappers.vector 中）
    • VectorListInfo -> vector.DictInfoToList
  • 添加的封装器
    • DelayObservation - 为下一个观测和奖励添加延迟
    • DtypeObservation - 修改环境观察空间的数据类型
    • MaxAndSkipObservation - 将跳过 n 个观测值，并将最后 2 个观测值取最大值，灵感来自 Atari 环境针对其他环境的启发式方法
    • StickyAction - 以概率随机重复动作，以进行一步，返回最终观测值和步骤的奖励总和。灵感来自 Atari 环境启发式方法
    • JaxToNumpy - 将基于 Jax 的环境转换为使用基于 Numpy 的输入和输出数据进行 reset、step 等操作
    • JaxToTorch - 将基于 Jax 的环境转换为使用基于 PyTorch 的输入和输出数据进行 reset、step 等操作
    • NumpyToTorch - 将基于 Numpy 的环境转换为使用基于 PyTorch 的输入和输出数据进行 reset、step 等操作

对于所有封装器，我们都添加了示例代码文档和变更日志，以帮助未来的研究人员了解所做的任何更改。请参阅以下 page 以获取示例。

函数式环境

Gymnasium 的 Env 的重要优势之一是它通常只需要最少的底层环境规范信息，但这会使此类环境更难以应用于规划、搜索算法和理论研究。我们正在提出 FuncEnv 作为 Env 的替代定义，它更接近马尔可夫决策过程定义，向用户公开更多函数，包括观察、奖励和终止函数以及环境的原始状态作为单个对象。

from typing import Any
import gymnasium as gym
from gymnasium.functional import StateType, ObsType, ActType, RewardType, TerminalType, Params

class ExampleFuncEnv(gym.functional.FuncEnv):
  def initial(rng: Any, params: Params | None = None) → StateType
    …
  def transition(state: StateType, action: ActType, rng: Any, params: Params | None = None) → StateType
    …
  def observation(state: StateType, params: Params | None = None) → ObsType
    …
  def reward(
      state: StateType, action: ActType, next_state: StateType, params: Params | None = None
  ) →   RewardType
    …
  def terminal(state: StateType, params: Params | None = None) → TerminalType
    …

FuncEnv 要求 initial 和 transition 函数返回一个新状态，给定其作为 Env.step 和 Env.reset 的部分实现的输入。因此，用户可以采样（和保存）一系列输入的下一个状态，以用于规划、搜索等。给定状态，observation、reward 和 terminal 为用户提供显式定义，以了解每个定义如何影响环境的输出。

其他错误修复

  • 由于 cython==3 问题，限制 gymnasium[mujoco-py] 的 cython 版本，作者：@pseudo-rnd-thoughts (#616)
  • 修复 MuJoCo 环境类型问题，作者：@Kallinteris-Andreas (#612)
  • 由 @logan-dunbar 修复了具有自定义宽度值的 mujoco 渲染问题 (#634)
  • 修复环境检查器，以正确报告无限边界，由 @chrisyeh96 (#708)
  • 修复 register(kwargs) 的类型提示，从 **kwargs 更改为 kwargs: dict | None = None，由 @younik (#788)
  • 修复 CartPoleVectorEnv 步骤计数器在 reset 时未重置为零的问题，作者：@TimSchneider42 (#886)
  • 修复自定义环境的异步向量环境注册问题，作者：@RedTachyon (#810)

其他新功能

  • 新的 MuJoCo v5 环境（更改和性能图表将包含在另一篇博文中），作者：@Kallinteris-Andreas (#572)
  • 在 MuJoCo 人工渲染中添加对更改查看窗口大小的支持，作者：@logan-dunbar (#635)
  • 由 @guyazran (#731) 在 MuJoCo 渲染中添加了对离屏尺寸和场景几何形状的更多控制
  • 由 @RogerJL (#789) 和 @pseudo-rnd-thoughts (#811) 在 JaxToNumpy、JaxToTorch 和 NumpyToTorch 中添加了处理 NamedTuples 的支持
  • 由 @jamartinh (#830) 为 FrameSkipObservation 添加了 padding_type 参数，以选择填充观察
  • 由 @Kallinteris-Andreas (#748) 为 check_environments_match 添加了渲染检查

弃用

文档变更

完整变更日志: v0.29.0...v1.0.0a1

v0.29.1

发布于 2023-08-21 - GitHub - PyPI

一个最小版本，修复了 Wrapper.__getattr__ 产生的警告。
特别是，此函数将在 v1.0.0 中移除，但报告的解决方案不正确，更新后的解决方案仍然显示警告（由于技术性的 python 原因）。

更改

  • Wrapper.__getattr__ 警告报告了不正确的新函数 get_attr，而不是 get_wrapper_attr
  • 当使用 get_wrapper_attr 时，由于 get_wrapper_attr 使用了底层使用 __getattr__ 的 hasattr，因此仍然会引发 __getattr__ 警告。因此，已更新以移除意外的警告。
  • 向 VectorEnvWrapper.__getattr__ 添加警告，以指定它也在 v1.0.0 中被弃用

完整变更日志: v0.29.0...v0.29.1

v0.29.0

发布于 2023-07-14 - GitHub - PyPI

v0.29.0 发行说明

我们最终为 Gymnasium 提供了软件引用，并计划在 v1.0 之后发布相关论文，感谢过去 3 年中所有为 Gym 和 Gymnasium 做出贡献的人员 (#590)

@misc{towers_gymnasium_2023,
        title = {Gymnasium},
        url = {https://zenodo.org/record/8127025},
        abstract = {An API standard for single-agent reinforcement learning environments, with popular reference environments and related utilities (formerly Gym)},
        urldate = {2023-07-08},
        publisher = {Zenodo},
        author = {Towers, Mark and Terry, Jordan K. and Kwiatkowski, Ariel and Balis, John U. and Cola, Gianluca de and Deleu, Tristan and Goulão, Manuel and Kallinteris, Andreas and KG, Arjun and Krimmel, Markus and Perez-Vicente, Rodrigo and Pierré, Andrea and Schulhoff, Sander and Tai, Jun Jet and Shen, Andrew Tan Jin and Younis, Omar G.},
        month = mar,
        year = {2023},
        doi = {10.5281/zenodo.8127026},
}

Gymnasium 有一个 conda 包，conda install gymnasium。感谢 @ChristofKaufmann 完成此项工作

重大更改

  • 删除对 Python 3.7 的支持，Python 3.7 已达到其生命周期结束支持，作者：@Kallinteris-Andreas in #573
  • 更新 MuJoCo Hopper 和 Walker2D 模型以与 MuJoCo >= 2.3.3 配合使用，作者：@Kallinteris-Andreas in #589
  • 为将在 v1.0 中移除的几个功能添加弃用警告：Wrapper.__get_attr__、gymnasium.make(..., autoreset=True)、gymnasium.make(..., apply_api_compatibility=True)、Env.reward_range 和 gymnasium.vector.make。有关其建议的替代方案，请参阅 #535
  • 为 Box 边界 low > high、low == inf 和 high == -inf 引发错误，作者：@jjshoots in #495
  • 在 data_equivalence() 中为 NumPy 数组添加 dtype 测试，作者：@pseudo-rnd-thoughts in #515
  • 从 gymnasium 包装器中移除 Jumpy，因为它只是部分实现，测试和使用有限，作者：@pseudo-rnd-thoughts in #548
  • 更新项目需求，jax>=0.4，作者：@charraut in #373

新功能

  • 移除对 pygame 版本的限制，pygame>=2.1.3，作者：@pseudo-rnd-thoughts in #558
  • 向 MultiDiscrete 空间添加 start 参数，类似于 Discrete(..., start) 参数，作者：@Rayerdyne in #557
  • 添加测试以 check_env，检查关闭已关闭的环境是否不会引发错误，作者：@pseudo-rnd-thoughts in #564
  • 在初始化时，如果环境具有无效的渲染模式 (None, "human", "ansi")，则 wrapper.RecordVideo 会抛出错误，作者：@robertoschiavone in #580
  • 添加 MaxAndSkipObservation 包装器，作者：@LucasAlegre in #561
  • 添加 check_environments_match 函数，用于检查两个环境是否相同，作者：@Kallinteris-Andreas in #576
  • 添加性能调试实用程序，utils/performance.py，作者：@Kallinteris-Andreas in #583
  • 添加了基于 Jax 的悬崖行走环境，作者：@balisujohn in #407
  • MuJoCo
  • 实验性
    • 在 gymnasium.experimental.wrappers 中添加了已弃用的包装器错误，作者：@charraut in #341
    • 向 RecordVideoV0 添加了 fps 参数，用于自定义 fps 值，该值将覆盖环境的内部 render_fps 值，作者：@younik in #503
    • 为 lambda 观察、动作和奖励包装器添加了实验性向量包装器，作者：@pseudo-rnd-thoughts in #444

Bug Fixes（Bug 修复）

  • 修复了 spaces.Dict.keys() 为 key in keys 时为 False 的问题，作者：@pseudo-rnd-thoughts in #608
  • 根据边界更新 wrappers.RescaleAction 的动作空间，作者：@mmcaulif in #569
  • 移除了被动环境检查器中针对无限 Box 边界的警告，作者：@pseudo-rnd-thoughts in #435
  • 还原 Lunar Lander 观察空间更改，作者：@alexdlukens in #512
  • 修复了 check_env 中的 URL 链接，作者：@robertoschiavone in #554
  • 将 shimmy[gym] 更新为 shimmy[gym-v21] 或 shimmy[gym-v26]，作者：@elliottower in #433
  • 修复了实验性向量环境和包装器中的几个问题，作者：@pseudo-rnd-thoughts in #516
  • 视频记录器包装器
    • 修复了 VideoRecorder 在 reset 时清空 recorded_frames 而不是 frames 的问题，作者：@voidflight in #518
    • 移除了 VideoRecorder.close 中的 Env.close，作者：@qgallouedec in #533
    • 修复了 VideoRecorder 和 RecordVideoV0 以移动 import moviepy，这样 __del__ 不会引发 AttributeErrors，作者：@pseudo-rnd-thoughts in #553
  • Mujoco

文档更新

完整变更日志：v0.28.1...v0.29.0

v0.28.1

发布于 2023-03-25 - GitHub - PyPI

v0.28.1 发行说明

修复若干问题的紧急小版本发布

  • 修复 gymnasium.vector 作为 gymnasium/__init__.py，因为它没有被导入 #403
  • 更新第三方环境，以区分支持 gymnasium 和 gym 的环境，并使其风格保持一致 #404
  • 更新 v0.28 的文档，因为首页 gif 的链接错误，实验性文档缺失，并添加 gym 发行说明 #405

完整变更日志：v0.28.0...v0.28.1

v0.28.0

发布于 2023-03-24 - GitHub - PyPI

v0.28.0 发行说明

此版本引入了对 Gymnasium 环境可复现性的改进支持，特别是对于离线强化学习。gym.make 现在可以创建整个环境堆栈，包括包装器，以便训练库或离线数据集可以指定用于环境的所有参数和包装器。对于大多数标准用法 (gym.make(”EnvironmentName-v0”))，这将是向后兼容的，但某些相当不常见的情况（即 env.spec 和 env.unwrapped.spec 返回不同的 specs）除外，这是一个重大更改。有关更多信息，请参阅可复现性详细信息部分。
在 v0.27 中，我们添加了 experimental 文件夹，以便我们开发几个新功能（包装器和硬件加速环境）。我们引入了一个新的实验性 VectorEnv 类。此类不继承自标准 Env 类，并将允许更高效的并行化功能。我们计划在未来几个小版本中改进实现并添加基于向量的包装器。
此外，我们优化了模块加载，以便仅在用户导入需要 PyTorch 或 Jax 的包装器时才加载它们，而不是在 import gymnasium 时加载。

可复现性详细信息

在以前的版本中，Gymnasium 支持 gym.make(spec)，其中 spec 是来自 gym.spec(str) 或 env.spec 的 EnvSpec，并且与基于字符串的 gym.make(“”) 的工作方式相同。在这两种情况下，都无法指定应应用于环境的其他包装器。在此版本中，我们在 EnvSpec 中添加了 additional_wrappers，用于指定应用于基础环境的包装器（TimeLimit、PassiveEnvChecker、Autoreset 和 ApiCompatibility 未包含在内，因为它们在其他字段中指定）。
这个附加字段将允许用户准确地保存或重现用于策略训练或生成离线 RL 数据集的环境。我们提供了一个 json 转换器函数 (EnvSpec.to_json) 用于将 EnvSpec 保存为“安全”文件类型，但是有几种情况（NumPy 数据、函数）无法保存为 json。在这些情况下，我们建议使用 pickle，但请注意，这可能允许远程用户在 spec 中包含恶意数据。

import gymnasium as gym

env = gym.make("CartPole-v0")
env = gym.wrappers.TimeAwareObservation(env)
print(env)  
# <TimeAwareObservation<TimeLimit<OrderEnforcing<PassiveEnvChecker<CartPoleEnv<CartPole-v0>>>>>>
env_spec = env.spec
env_spec.pprint()
# id=CartPole-v0
# reward_threshold=195.0
# max_episode_steps=200
# additional_wrappers=[
# 	name=TimeAwareObservation, kwargs={}
# ]

import json
import pickle

json_env_spec = json.loads(env_spec.to_json())
pickled_env_spec = pickle.loads(pickle.dumps(env_spec))
recreated_env = gym.make(json_env_spec)
print(recreated_env)  
# <TimeAwareObservation<TimeLimit<OrderEnforcing<PassiveEnvChecker<CartPoleEnv<CartPole-v0>>>>>>
# Be aware that the `TimeAwareObservation` was included by `make`

为了支持这种类型的重建，包装器必须继承自 gym.utils.RecordConstructorUtils，以允许 gym.make 知道使用哪些参数来创建包装器。Gymnasium 已为所有内置包装器实现了这一点，但对于外部项目，应将其添加到每个包装器。为此，请在包装器的构造函数的第一行调用 gym.utils.RecordConstructorUtils.__init__(self, …)，其中包含与传递给包装器构造函数的 l 关键字参数相同的参数，但 env 除外。例如，请参阅 Atari Preprocessing wrapper
有关更详细的讨论，请参阅原始 PR - #292 和 #355

其他主要更改

  • 在 Gymnasium v0.26 中，添加了 GymV22Compatibility 环境以支持 Gymnasium 中基于 Gym 的环境。但是，名称不正确，因为该环境支持 Gym 的 v0.21 API，而不是 v0.22，因此，我们已将其更新为 GymV21Compatibility 以准确反映支持的 API。 #282
  • Sequence 空间允许在观察或动作空间样本中包含动态数量的元素。为了提高效率，我们添加了一个 stack 参数，它可以支持比 tuple 更有效的元素表示，而 tuple 是以前支持的。 #284
  • Box.sample 以前对于上界空间会错误地进行裁剪，这样如果 dtype 是离散或布尔值，则永远无法采样 0。现在已修复，以便在这些情况下可以采样 0。 #249
  • 如果安装了 jax 或 pytorch，那么在 import gymnasium 时也会加载这两个模块，从而导致加载时间显着减慢。现在已修复此问题，只有在用户加载特定包装器时才会加载 jax 和 torch。 #323
  • 在 v0.26 中，我们为 Wrapper 添加了参数，以允许为包装器及其子环境指定不同的观察和动作类型。但是，这引发了 pyright 和 mypy 的类型问题，现在已通过 Wrapper 具有四个泛型参数 [ObsType, ActType, WrappedEnvObsType, WrappedEnvActType] 修复了此问题。 #337
  • 在 v0.25 和 0.v26 中，引入了几个新的空间类型：Text、Graph 和 Sequence，但是向量实用程序函数未更新以支持这些空间。已将对这些空间的支持添加到实验性向量空间实用程序函数：batch_space、concatenate、iterate 和 create_empty_array。 #223
  • 由于缺乏测试，实验性有状态观察包装器（FrameStackObservation、DelayObservation 和 TimeAwareObservation）无法按预期工作。这些包装器现已修复，并已添加测试。 #224

次要更改

  • 允许禁用和启用 NormalizeX 包装器的统计信息，以便在评估期间使用，由 @raphajaner 在 #268 中完成
  • 由 @DrRyanHuang 在 #278 中修复 lunar_lander.py 中的 AttributeError
  • 由 @valentin-cnt 在 #281 中添加对文档字符串 (doctest) 的测试，以使文档字符串与实现相匹配
  • 由 @howardh 在 #321 中修复类型提示并添加 __all__ dunder
  • 由 @valentin-cnt 在 #327 中修复 gymnasium/spaces 中的类型提示错误
  • 由 @pseudo-rnd-thoughts 在 #339 中更新实验性向量共享内存实用程序函数
  • 由 @jjshoots 在 #332 中将 Gymnasium Notices 更改为 Farama Notifications
  • 由 @balisujohn 在 #338 中添加基于 Jax 的 Blackjack 环境

文档变更

  • 由 @Matyasch 在 #279 中修复文档中 MultiBinary 和 MultiDiscrete 类的引用
  • 由 @nerdyespresso 在 #304 中添加 Comet 集成
  • 由 @pseudo-rnd-thoughts 在 #330 中更新 atari 文档
  • 由 @mihaic 在 #331 中记录 Box 整数边界
  • 由 @valentin-cnt 在 #329 中添加文档字符串解析器，以删除 Gymnasium 网站中的重复内容
  • 由 @keyb0ardninja 在 #333 中修复基本用法页面中的语法错误
  • 由 @mgoulao 在 #340 中更新 docs/README.md 以链接到 docs 的新 CONTRIBUTING.md
  • MuJoCo/Ant 澄清 v3（和更早版本）上缺少 use_contact_forces，由 @Kallinteris-Andreas 在 #342 中完成

更新内容

感谢我们在本版本中的新贡献者：@Matyasch, @DrRyanHuang, @nerdyespresso, @khoda81, @howardh, @mihaic, 和 @keyb0ardninja。

完整变更日志：v0.27.1...v0.28.0

v0.27.1

发布于 2023-01-20 - GitHub - PyPI

发行说明

错误修复

新功能/改进

  • 由 @PaulMest 在 #235 中，将 LunarLander-v2 step 性能提高 >1.5 倍
  • 由 @nidhishs 在 #238 中，为 StepAPICompatibility 包装器添加向量环境支持
  • 由 @jjshoots 在 #241 中，允许 sequence 在特征空间为 Box 时接受堆叠的 np 数组
  • 由 @pseudo-rnd-thoughts 在 #225 中，改进从插件引发错误时的警告
  • 由 @mgoulao 在 #257 中，将变更日志（发行说明）添加到网站
  • 由 @younik 在 #246 中，实现 RecordVideoV0
  • 由 @PierreMardon 在 #267 中，在取消展平 discrete 和 multidiscrete 失败时添加显式错误消息

文档更新

感谢 Gymnasium 的新贡献者，如果您想参与其中，请加入我们的 discord 服务器。链接在自述文件中。

完整变更日志: v0.27.0...v0.27.1

v0.27.0

发布于 2022-12-12 - GitHub - PyPI

发行说明

Gymnasium 0.27.0 是我们 Gymnasium 的首个主要版本。它有几个重要的新功能，以及许多小的错误修复和代码质量改进，因为我们正在处理我们的积压工作。除了删除 Python 3.6 支持和移除 mujoco Viewer 类，改为 MujocoRendering 类之外，应该没有重大更改。您应该能够轻松地将使用 Gymnasium 0.26.x 的代码升级到 0.27.0。

像往常一样，我们的开发路线图在此处公开 here，您可以关注我们未来的计划。仍然计划的唯一大的破坏性更改是将选定的环境切换为使用硬件加速物理引擎，以及我们长期以来计划彻底修改向量 API 和内置包装器。

此版本值得注意的是包含库的全新部分：gymnasium.experimental。我们正在添加新的功能、包装器和功能性环境 API（如下讨论），供用户测试和试用，以查找错误并提供反馈。

新包装器

这些新的包装器可在 gymnasium.experimental.wrappers 中访问，请参阅 https://gymnasium.org.cn/main/api/experimental/ 中的完整列表，旨在替换 gymnasium v0.30.0 中的包装器，并包含多项改进

  • (正在进行中) 支持任意复杂的观察/动作空间。随着强化学习的发展，动作和观察空间变得越来越复杂，当前的包装器在实现时并未考虑到这一点。
  • 支持基于 Jax 的环境。对于硬件加速环境，即用 Jax 编写的 Brax 和类似的基于 PyTorch 的程序，NumPy 不再是编写环境的唯一选择。因此，这些升级将使用 Jumpy，这是 Farama Foundation 开发的一个项目，旨在为 NumPy 函数的很大一部分子集提供 NumPy、Jax 以及未来 PyTorch 数据的自动兼容性。
  • 更多包装器。像 Supersuit 这样的项目旨在为强化学习带来更多包装器，但是，许多用户并不知道这些包装器，因此我们计划将这些包装器移至 Gymnasium 中。如果我们遗漏了上面列表中的常见包装器，请创建 issue，我们有兴趣添加它。
  • 版本控制。与环境一样，包装器的实现细节可能会导致代理性能的变化。因此，我们建议为所有包装器添加版本号，例如，LambaActionV0。我们不希望这些版本号经常更改，其行为将类似于环境版本号。这应确保所有用户都知道何时重大更改可能会影响您的代理在环境和包装器上的性能。此外，我们希望这将提高未来强化学习的可重复性，这对于学术界至关重要。
  • 在 v28 中，我们旨在重写 VectorEnv，使其不继承自 Env，因此将提供新的向量化版本的包装器。

核心开发者: @gianlucadecola, @RedTachyon, @pseudo-rnd-thoughts

功能性 API

Env 类为环境的编写提供了非常通用的结构，从而在程序结构中具有很高的灵活性。但是，这限制了有效向量化环境、划分环境代码等的能力。因此，gymnasium.experimental.FuncEnv 为环境实现提供了更严格的结构，其中包含无状态函数，用于环境实现的每个阶段。此类不继承自 Env，并且需要翻译/兼容性类才能执行此操作。我们已经提供了 FuncJaxEnv，用于将基于 jax 的 FuncEnv 转换为 Env。我们希望这将有助于提高环境实现的可读性，并为向量化其代码的用户带来潜在的速度提升。

此 API 非常实验性，因此未来可能会发生变化。我们对尝试使用该 API 的用户的反馈感兴趣，我们认为这对于探索强化学习规划、基于模型的强化学习和修改奖励等环境功能的用户尤其重要。

核心开发者: @RedTachyon, @pseudo-rnd-thoughts, @balisujohn

其他主要更改

  • 重构 Mujoco 渲染机制以使用单独的线程进行 OpenGL。删除 Viewer，改为 MujocoRenderer，后者可以用于离屏、人工和其他渲染模式，由 @rodrigodelazcano 在 #112
  • 添加弃用警告，将 gym.make(..., apply_env_compatibility=True) 替换为 gym.make("GymV22Environment", env_id="...")，由 @pseudo-rnd-thoughts 在 #125
  • 添加 gymnasium.pprint_registry() 以漂亮地打印 gymnasium 注册表，由 @kad99kev 在 #124
  • 将 Discrete.dtype 更改为 np.int64，使样本为 np.int64 而不是 python int。由 @pseudo-rnd-thoughts 在 #141
  • 添加从 OpenAI Gym v21 到 v26 的迁移指南，由 @pseudo-rnd-thoughts 在 #72
  • 为 core.py 中的 Env、Wrapper 等添加完整的类型提示，由 @pseudo-rnd-thoughts 在 #39
  • 为 gymnasium.spaces 中的所有 spaces 添加完整的类型提示，由 @pseudo-rnd-thoughts 在 #37
  • 使 play() 中的窗口可调整大小，由 @Markus28 在 #190
  • 添加 REINFORCE 实现教程，由 @siddarth-c 在 #155

错误修复和文档更改

  • 移除 VideoRecorder 包装器中的自动关闭，由 @younik 在 #42
  • 更改 seeding.np_random 错误消息以报告种子类型，由 @theo-brown 在 #74
  • 在 MujocoEnv 错误消息中包含形状，由 @ikamensh 在 #83
  • 添加漂亮的特性/GitHub issue 表单，由 @tobirohrer 在 #89
  • 在 check_env 和 PassiveEnvChecker 中添加了对渲染返回数据的测试，由 @Markus28 在 #117
  • 修复文档字符串并更新经典控制环境的动作空间描述，由 @Thytu 在 #123
  • 修复根目录 __init__.py 中的 __all__ 以指定正确的文件夹，由 @pseudo-rnd-thoughts 在 #130
  • 修复 play() 断言错误，由 @Markus28 在 #132
  • 更新 Frozen Lake is_slippy 的文档，由 @MarionJS 在 #136
  • 修复当 render_mode 为 None 时的警告，由 @younik 在 #143
  • 在文档中添加了 is_np_flattenable 属性，由 @Markus28 在 #172
  • 更新了 Wrapper 文档，由 @Markus28 在 #173
  • 更新了 spaces 文档的格式，由 @Markus28 在 #174
  • 对于 FrozenLake，在随机地图生成中添加种子，由 @kir0ul 在 #139
  • 添加关于从扁平化 spaces 中 unflattening 样本时出现问题的注释，由 @rusu24edward 在 #164
  • 将 pusher 环境页面包含到网站中，由 @axb2035 在 #171
  • 在 AsyncVectorEnv 中添加检查，以在 step_wait 中拆分结果之前检查是否成功，由 @aaronwalsman 在 #178
  • 为 MuJoCo.Ant-v4.use_contact_forces 添加文档，由 @Kallinteris-Andreas 在 #183
  • 修复 README.md 中的错别字，由 @cool-RR 在 #184
  • 为 MuJoCo.Ant v4 变更日志添加文档，由 @Kallinteris-Andreas 在 #186
  • 修复 MuJoCo.Ant 文档中的动作顺序，由 @Kallinteris-Andreas 在 #208
  • 为整个代码库添加 raise-from 异常，由 @cool-RR 在 #205

幕后更改

v0.26.3

发布于 2022-10-24 - GitHub - PyPI

发行说明

注意：ale-py (atari) 尚未更新到 Gymnasium。因此 pip install gymnasium[atari] 将会失败，这将在 v0.27 中修复。同时，使用 pip install shimmy[atari] 进行修复。

Bug Fixes（Bug 修复）

  • 添加了 Gym-Gymnasium 兼容性转换器，允许用户在 Gymnasium 中使用 Gym 环境，由 @RedTachyon 在 #61
  • 修改 HumanRendering 和 RenderCollection 包装器中的元数据，使其具有正确的元数据，由 @RedTachyon 在 #35
  • 简化了 EpisodeStatisticsRecorder 包装器，由 @DavidSlayback 在 #31
  • 修复 MultiDiscrete.flatten() 中的整数溢出，由 @olipinski 在 #55 中完成
  • 重新添加为 Mujoco 环境指定 XML 文件的功能，由 @Kallinteris-Andreas 在 #70 中完成

文档变更

完整更新日志: v0.26.2...v0.26.3

感谢新的贡献者

v0.26.2

发布于 2022-10-05 - GitHub - PyPI

此版本是 Gym v26.2 的上游版本

Bug 修复

  • 由于 reset 现在返回 (obs, info)，这导致在向量环境中，最终步骤的 info 被覆盖。现在，最终的 observation 和 info 包含在 info 中，作为 "final_observation" 和 "final_info" @pseudo-rnd-thoughts
  • 当尝试在未指定 render_mode 的情况下渲染时添加警告 @younik
  • 更新 Atari 预处理，以便 wrapper 可以被 pickled @vermouth1992
  • Github CI 得到加强，使得 CI 仅具有读取权限 @sashashura
  • 澄清并修复 GraphInstance 中的错别字 @ekalosak

v0.26.1

发布于 2022-09-16 - GitHub - PyPI

此版本是 Gym v26.1 的上游版本

此外，gym docs 仓库已与新网站 https://gymnasium.org.cn/ 合并

v0.26.0: 初始版本

发布于 2022-09-13 - GitHub - PyPI

这是 Gymnasium 的第一个版本，Gymnasium 是 OpenAI Gym 的一个维护的分支

此版本与 Gym v0.26.0 完全相同，除了项目名称 (Gymnasium) 和行为准则

阅读 #12 以了解变更路线图