Gymnasium 釋出說明

v1.2.0

釋出於 2025-06-27 - GitHub - PyPI

Gymnasium v1.2.0

在 Gym v0.24 中，添加了使用不同模擬器（mujoco，而非 mujoco-py）的 v4 MuJoCo 環境。
由於 v0.24 釋出至今已有三年，且 mujoco-py 已停止維護，這限制了我們對 Python 3.13 的支援能力。
因此，在此版本中，我們已將 MuJoCo v2 和 v3 遷移到 Gymnasium-Robotics 專案，這意味著無法升級到 v4 或 v5 MuJoCo 環境的使用者應將其程式碼更新為

import gymnasium as gym
import gymnasium_robotics  # `pip install "gymnasium-robotics[mujoco-py]"`

gym.register_envs(gymnasium_robotics)  # optional

env = gym.make("Humanoid-v3")

此外，我們還添加了對 Python 3.13 的支援（並跟隨 NumPy 及其他專案放棄了對 Python 3.8 和 3.9 的支援）。

新特性

  • 新增 `AddWhiteNoise` 和 `ObstructView` 封裝器，由 @sparisi 實現，用於在 RGB 渲染中新增噪聲，覆蓋整個影像或部分割槽域 (#1243)
  • 為計程車環境添加了多雨和反覆無常的選項，這些選項由 @foreverska 在原始論文中實現 (#1315)
  • 新增 `wrappers.ArrayConversion`，這是一個由 @amacati 實現的通用轉換封裝器，用於在相容 Array API 的框架（如 NumPy、Torch、Jax 等）之間進行轉換 (#1333)
  • 在 RecordVideo 封裝器上新增垃圾回收器，以防止記憶體溢位問題，由 @vicbentu 實現 (#1378)

錯誤修復

此外，此版本還包括對文件的眾多更新，最重要的是對介紹性頁面的更新，旨在使 Gymnasium 或 RL 的新使用者更容易理解。

完整更新日誌: v1.1.1...v1.2.0

Gymnasium v1.1.1

釋出於 2025-03-06 - GitHub - PyPI

更改

  • 移除 `mujoco_env.py` 中基於 MuJoCo 的環境對元資料渲染模式的斷言 (#1328)
  • 由 @pkuderov 更新 `wrappers.vector.NumpyToTorch`，使其引用 `numpy` 而非 `jax` (#1319)

完整更新日誌: v1.1.0...v1.1.1

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 中，我們為空間添加了掩碼功能，即 `space.sample(mask=...)`，用於邏輯上掩蓋空間中可能的樣本。#1310 透過 `space.sample(probability=...)` 為每個空間添加了機率掩碼，以指定每個樣本的機率，這對於輸出動作機率分佈的 RL 策略非常有用。
  • 對於 MuJoCo 環境，使用者可以選擇使用 RGB 影像或基於深度的影像渲染機器人。以前，只能訪問 RGB 或深度渲染。Gymnasium v1.1 添加了 RGBD 渲染，可將 RGB 和基於深度的影像作為單個輸出。
  • 在 Gymnasium v1.0 中，我們透過 `JaxToTorch`、`JaxToNumpy`、`NumpyToTorch` 等改進了 `jax`、`torch` 和 `numpy` 之間的轉換封裝器。在 v1.1 中，我們改進了封裝器以支援渲染並與完整的 dlpack API 相容。

新特性

  • 由 @mariojerez 實現的帶機率掩碼的空間取樣 (#1310)
  • 由 @DavidPL1 為 MuJoCo 新增 RGB + 深度渲染 (#1229)
  • 由 @amacati 新增對 `JaxToNumpy`、`JaxToTorch` 和 `NumpyToTorch` 的渲染支援 (#1306)
  • 由 @amacati 新增對 dlpack API 的完全支援 (#1299)
  • 由 @sparisi 啟用 StickyAction 封裝器，使其能夠重複舊動作超過 1 步 (#1240)
  • 由 @howardh 新增 `wrappers.vector.TransformObs/Action` 對單個觀測/動作空間引數的支援 (#1288)
  • 由 @duburcqa 改進封裝器的 'set_wrapper_attr' 以修改變數更新方式 (#1294)
  • 由 @li-plus 允許 `AtariPreprocessing` 支援非方形觀測 (#1312)
  • 由 @pseudo-rnd-thoughts 改進 `Wrapper` 和 `VectorWrapper` 的錯誤檢查 (#1260)

錯誤修復

文件更改

  • 由 @artemmiyy 修復 21點遊戲中取樣值（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 認為正在發生一些事情並且需要此匯入語句。

向量環境

為了提高環境的取樣速度，向量化是同時取樣同一環境多個例項的最簡單方法之一。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.0 包含一個示例向量倒立擺環境，該環境僅用 NumPy 編寫，執行速度比使用 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` 類。有關新資訊，請參閱向量封裝器頁面。

為提高向量環境的效率，自動重置（autoreset）是一項常見功能，它允許子環境在所有子環境完成之前進行重置。以前在 Gym 和 Gymnasium 中，自動重置發生在環境回合結束的同一時間步。最終的觀察和資訊會儲存在時間步的資訊中，即 info["final_observation"] 和 info[“final_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 字典）以及必須提取最終觀察值才能正確訓練智慧體的麻煩，例如 這個示例。因此，在 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)

對於在策略 rollout，為了適應自動重置，需要對新回合中的第一個觀察值（done[t+1]）進行誤差掩碼，以防止計算回合中最後一個觀察值和第一個觀察值之間的誤差。

最後，我們改進了 AsyncVectorEnv.set_attr 和 SyncVectorEnv.set_attr 函式，使其使用 Wrapper.set_wrapper_attr，允許使用者在環境堆疊中已存在的任何位置設定變數。以前，這是不可能的，使用者只能修改環境堆疊中“頂部”包裝器中的變數，而不是實際環境本身。

封裝器 (Wrappers)

以前，一些包裝器（wrapper）可以同時支援標準環境和向量環境，但這種支援並未標準化，並且不清楚哪些包裝器支援向量環境，哪些不支援。對於 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 - 修改環境觀察空間的 dtype
    • MaxAndSkipObservation - 將跳過 n 個觀察值，並取最近 2 個觀察值的最大值，靈感來自 Atari 環境啟發式演算法，適用於其他環境
    • StickyAction - 以一定機率隨機重複動作，並返回最終觀察值和多個時間步的獎勵總和。靈感來自 Atari 環境啟發式演算法
    • JaxToNumpy - 將基於 Jax 的環境轉換為使用基於 Numpy 的輸入和輸出資料進行 reset、step 等操作
    • JaxToTorch - 將基於 Jax 的環境轉換為使用基於 PyTorch 的輸入和輸出資料進行 reset、step 等操作
    • NumpyToTorch - 將基於 Numpy 的環境轉換為使用基於 PyTorch 的輸入和輸出資料進行 reset、step 等操作

對於所有包裝器，我們都添加了示例程式碼文件和更新日誌，以幫助未來的研究人員瞭解所做的任何更改。例如，請參閱以下頁面。

函式式環境

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 對環境和空間進行種子設定以使用隨機初始種子值，但無法知道這些初始種子值是什麼。我們已透過 #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>= 3 和 Pusher 的使用者造成問題。因此，我們停用了 mujoco>= 3 下的 v4 環境，並更新到 MuJoCo v5 中的模型，該模型能產生與 v4 和 mujoco< 3 類似更預期的行為 (#1019)。

  • 作為兩年前新增的 v4 環境的後續，新的 v5 MuJoCo 環境修復了一致性問題，添加了新功能並更新了文件 (#572)。此外，我們已決定將基於 mujoco-py 的（v2 和 v3）環境標記為已棄用，並計劃在未來從 Gymnasium 中移除它們 (#926)。

  • 由於修復了兩個錯誤，Lunar Lander 版本從 v2 升級到 v3。第一個修復了環境的確定性，使得世界物件在重置時不會完全被銷燬，從而避免了在特定情況下的非確定性 (#979)。第二，風生成（預設關閉）在每次重置時並未隨機生成，因此我們已更新此功能，以確保回合之間的統計獨立性 (#959)。

  • CarRacing 版本從 v2 升級到 v3，以改變環境的結束方式，即當代理完成賽道時，環境將終止而非截斷。

  • 我們已移除 pip install "gymnasium[accept-rom-license]"，因為 ale-py>=0.9 現在已隨 roms 一起打包，這意味著使用者不再需要單獨安裝帶有 autoroms 的 Atari roms。

其他錯誤修復

  • spaces.Box 允許低於或高於 dtype 範圍的值，這可能導致一些非常奇怪的邊緣情況，而 @pseudo-rnd-thoughts 很難檢測到這些情況 (#774)
  • 由於 cython==3 問題，@pseudo-rnd-thoughts 限制了 gymnasium[mujoco-py] 的 cython 版本 (#616)
  • @logan-dunbar 修復了 MuJoCo 渲染時自定義寬度值的問題 (#634)
  • @chrisyeh96 修復了環境檢查器以正確報告無限邊界 (#708)
  • @younik 將 register(kwargs) 的型別提示從 **kwargs 修復為 kwargs: dict | None = None (#788)
  • @RedTachyon 修復了 AsyncVectorEnv 中自定義環境的註冊問題 (#810)
  • @MischaPanch 移除了 v4+ MuJoCo 環境的 mujoco-py 匯入錯誤
    (#934)
  • 修復了 Tuple 和 Dict 空間共享記憶體讀取問題 (#941)
  • 修復了 Multidiscrete.from_jsonable 在 Windows 上的問題 (#932)
  • 移除了 play 渲染歸一化 (#956)
  • @mantasu 修復了 to_torch 轉換中未使用的裝置引數 (#1107)
  • @mantasu 修復了 GPU 上 PyTorch 到 NumPy 的轉換問題 (#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 環境

ale-py 提供 Atari 環境，其已在 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 不相容，原因是修復了一些 bug，發現智慧體需要推動的塊的模型密度是空氣密度。這顯然開始給使用 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。第一個修復了環境的確定性，使得世界物件在重置時不會完全被銷燬，從而避免了在特定情況下的非確定性 (#979)。第二，風生成（預設關閉）在每次重置時並未隨機生成，因此我們已更新此功能，以確保回合之間的統計獨立性 (#959)。

Box 空間取樣

發現 spaces.Box 允許低值和高值超出資料型別 (dtype) 的範圍 (#774)，這可能導致一些非常難以檢測的奇怪邊緣情況。我們希望這些更改能改善除錯和檢測空間無效輸入的能力，但是，如果您的環境出現與此相關的問題，請告知我們。

錯誤修復

  • 更新 CartPoleVectorEnv 以支援新的自動重置 API (#915)
  • 修復了 wrappers.vector.RecordEpisodeStatistics 中使用新自動重置 API 計算劇集長度的問題 (#1018)
  • 移除 v4+ MuJoCo 環境的 mujoco-py 匯入錯誤 (#934)
  • 修復 make_vec(**kwargs) 未傳遞給向量入口點環境的問題 (#952)
  • 修復了 Tuple 和 Dict 空間共享記憶體讀取問題 (#941)
  • 修復 Multidiscrete.from_jsonable 在 Windows 上的問題 (#932)
  • 移除 play 渲染標準化 (#956)

新特性

  • 新增 Python 3.12 支援
  • 新增一個新的 OneOf 空間，提供空間的獨佔聯合 (#812)
  • 更新 Dict.sample，使其使用標準 Python 字典而非 OrderedDict，因為已放棄對 Python 3.7 的支援 (#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 添加了 metadata 欄位 (#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）認為該匯入語句沒有作用。因此，我們引入了 gymnasium.register_envs 作為空操作函式（該函式實際上什麼都不做），以使 IDE 相信有事情正在發生，並且匯入語句是必需的。

注意：ALE-py、Minigrid 和 HighwayEnv 必須更新才能與 Gymnasium v1.0.0 相容，我們希望在 alpha 2 版本中完成所有受影響專案的更新。

向量環境

為了提高環境的取樣速度，向量化是同時取樣同一環境多個例項的最簡單方法之一。Gym 和 Gymnasium 提供了 VectorEnv 作為其基類，但其中一個問題是它繼承了 Env。這可能導致型別檢查（step 的返回型別在 Env 和 VectorEnv 中不同）、環境型別測試（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 預設使用異步向量化器）。欲瞭解更多資訊，請參閱函式的 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` 類。有關新資訊，請參閱向量封裝器頁面。

為了提高向量環境的效率，自動重置 (autoreset) 是一種常見功能，它允許子環境在所有子環境完成之前進行重置，而無需等待所有子環境都完成。以前在 Gym 和 Gymnasium 中，自動重置是在環境劇集結束的同一步驟中完成的，因此最終的觀察值和資訊會儲存在步驟的資訊中，即 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 字典）以及必須提取最終觀察結果才能正確訓練智慧體的麻煩，例如 此處。因此，在 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)

以前，一些包裝器（wrapper）可以同時支援標準環境和向量環境，但這種支援並未標準化，並且不清楚哪些包裝器支援向量環境，哪些不支援。對於 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 - 修改環境觀察空間的資料型別 (dtype)
    • MaxAndSkipObservation - 將跳過 n 個觀察值，並取最近 2 個觀察值的最大值，靈感來自 Atari 環境啟發式演算法，適用於其他環境
    • StickyAction - 以一定機率隨機重複動作，並返回最終觀察值和多個時間步的獎勵總和。靈感來自 Atari 環境啟發式演算法
    • JaxToNumpy - 將基於 Jax 的環境轉換為使用基於 Numpy 的輸入和輸出資料進行 reset、step 等操作
    • JaxToTorch - 將基於 Jax 的環境轉換為使用基於 PyTorch 的輸入和輸出資料進行 reset、step 等操作
    • NumpyToTorch - 將基於 Numpy 的環境轉換為使用基於 PyTorch 的輸入和輸出資料進行 reset、step 等操作

對於所有包裝器，我們都添加了示例程式碼文件和更新日誌，以幫助未來的研究人員瞭解所做的任何更改。例如，請參閱以下頁面。

函式式環境

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)
  • @younik 將 register(kwargs) 的型別提示從 **kwargs 修復為 kwargs: dict | None = None (#788)
  • 修復 CartPoleVectorEnv 步數計數器在 reset 時重置為零的問題，由 @TimSchneider42 完成 (#886)
  • 修復自定義環境的異步向量環境註冊問題，由 @RedTachyon 完成 (#810)

其他新功能

  • 新的 MuJoCo v5 環境（更改和效能圖表將包含在單獨的部落格文章中），由 @Kallinteris-Andreas 完成 (#572)
  • 在 MuJoCo 人工渲染中新增支援以更改觀察視窗的大小，由 @logan-dunbar 完成 (#635)
  • @guyazran 在 MuJoCo 渲染中對離屏尺寸和場景幾何體提供了更多控制 (#731)
  • @RogerJL (#789) 和 @pseudo-rnd-thoughts (#811) 在 JaxToNumpy、JaxToTorch 和 NumpyToTorch 中添加了對 NamedTuples 的處理支援
  • @jamartinh 為 FrameSkipObservation 添加了 padding_type 引數以選擇填充觀察值 (#830)
  • @Kallinteris-Andreas 為 check_environments_match 添加了渲染檢查 (#748)

棄用

文件變更

完整更新日誌: 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 內部使用了 hasattr，而 hasattr 又使用了 __getattr__，因此 __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 的支援，該版本已達到生命週期結束，由 @Kallinteris-Andreas 在 #573 中完成
  • 更新 MuJoCo Hopper & Walker2D 模型以與 MuJoCo >= 2.3.3 相容，由 @Kallinteris-Andreas 在 #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 在 #495 中完成
  • 在 data_equivalence() 中為 NumPy 陣列新增 dtype 測試，由 @pseudo-rnd-thoughts 在 #515 中完成
  • 從 gymnasium 包裝器中移除 Jumpy，因為它僅部分實現，測試和使用有限，由 @pseudo-rnd-thoughts 在 #548 中完成
  • 更新專案對 jax>=0.4 的要求，由 @charraut 在 #373 中完成

新特性

  • 移除 pygame 版本限制 pygame>=2.1.3，由 @pseudo-rnd-thoughts 在 #558 中完成
  • 為 MultiDiscrete 空間新增 start 引數，類似於 Discrete(..., start) 引數，由 @Rayerdyne 在 #557 中完成
  • 向 check_env 新增測試，確保關閉已關閉的環境不會引發錯誤，由 @pseudo-rnd-thoughts 在 #564 中完成
  • 在初始化時，如果環境具有無效的渲染模式 (None, "human", "ansi")，wrapper.RecordVideo 會丟擲錯誤，由 @robertoschiavone 在 #580 中完成
  • 新增 MaxAndSkipObservation 包裝器，由 @LucasAlegre 在 #561 中完成
  • 新增 check_environments_match 函式，用於檢查兩個環境是否相同，由 @Kallinteris-Andreas 在 #576 中完成
  • 新增效能除錯工具 utils/performance.py，由 @Kallinteris-Andreas 在 #583 中完成
  • 新增基於 Jax 的 Cliff Walking 環境，由 @balisujohn 在 #407 中完成
  • MuJoCo
  • 實驗性功能
    • 在 gymnasium.experimental.wrappers 中新增已棄用的包裝器錯誤，由 @charraut 在 #341 中提出
    • 為 RecordVideoV0 新增 fps 引數，用於自定義幀率值，該值將覆蓋環境內部的 render_fps 值，由 @younik 在 #503 中提出
    • 為 lambda 觀察、動作和獎勵包裝器新增實驗性向量包裝器，由 @pseudo-rnd-thoughts 在 #444 中提出

錯誤修復

  • 修復 spaces.Dict.keys()，因為 key in keys 曾為 False，由 @pseudo-rnd-thoughts 在 #608 中提出
  • 根據邊界更新 wrappers.RescaleAction 的動作空間，由 @mmcaulif 在 #569 中提出
  • 移除被動環境檢查器中關於無限 Box 邊界的警告，由 @pseudo-rnd-thoughts 在 #435 中提出
  • 回滾 Lunar Lander 觀察空間更改，由 @alexdlukens 在 #512 中提出
  • 修復 check_env 中的 URL 連結，由 @robertoschiavone 在 #554 中提出
  • 將 shimmy[gym] 更新為 shimmy[gym-v21] 或 shimmy[gym-v26]，由 @elliottower 在 #433 中提出
  • 修復實驗性向量環境和包裝器中的若干問題，由 @pseudo-rnd-thoughts 在 #516 中提出
  • 影片錄製器包裝器
    • 修復 VideoRecorder 在 reset 時清空 recorded_frames 而非 frames 的問題，由 @voidflight 在 #518 中提出
    • 從 VideoRecorder.close 中移除 Env.close，由 @qgallouedec 在 #533 中提出
    • 修復 VideoRecorder 和 RecordVideoV0，將 import moviepy 移動，以避免 __del__ 丟擲 AttributeErrors，由 @pseudo-rnd-thoughts 在 #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 返回不同的規範）除外，這是一個破壞性更改。有關更多資訊，請參閱可重現性詳情部分。
在 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，但請注意，這可能會允許遠端使用者在規範中包含惡意資料。

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, …)，並傳入與包裝器建構函式相同的關鍵字引數，除了 env。例如，請參見 Atari 預處理包裝器
有關更詳細的討論，請參閱原始 PR - #292 和 #355

其他重大變更

  • 在 Gymnasium v0.26 中，添加了 GymV22Compatibility 環境以支援 Gymnasium 中的基於 Gym 的環境。然而，該名稱不正確，因為該環境支援 Gym 的 v0.21 API，而不是 v0.22，因此，我們已將其更新為 GymV21Compatibility 以準確反映所支援的 API。 #282
  • Sequence 空間允許觀察或動作空間樣本中包含動態數量的元素。為了提高效率，我們添加了一個 stack 引數，它可以支援比之前支援的 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 和 v0.26 中引入了幾個新的空間型別：Text、Graph 和 Sequence，但向量實用函式沒有更新以支援這些空間。現在已將對這些空間的支援新增到實驗性向量空間實用函式中：batch_space、concatenate、iterate 和 create_empty_array。 #223
  • 由於缺乏測試，實驗性有狀態觀察包裝器（FrameStackObservation、DelayObservation 和 TimeAwareObservation）未能按預期工作。這些包裝器現已修復並添加了測試。 #224

次要變更

  • 允許在評估期間停用和啟用 NormalizeX 包裝器的統計資訊，由 @raphajaner 在 #268 中提出
  • 修復 lunar_lander.py 中的 AttributeError，由 @DrRyanHuang 在 #278 中提出
  • 新增文件字串測試 (doctest)，以使文件字串與實現匹配，由 @valentin-cnt 在 #281 中提出
  • 型別提示修復並添加了 __all__ 特殊方法，由 @howardh 在 #321 中提出
  • 修復 gymnasium/spaces 中的型別提示錯誤，由 @valentin-cnt 在 #327 中提出
  • 更新實驗性向量共享記憶體實用函式，由 @pseudo-rnd-thoughts 在 #339 中提出
  • 將 Gymnasium 通知更改為 Farama 通知，由 @jjshoots 在 #332 中提出
  • 添加了基於 Jax 的 Blackjack 環境，由 @balisujohn 在 #338 中提出

文件變更

  • 由 @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，以連結到新的文件貢獻指南 CONTRIBUTING.md。
  • 由 @Kallinteris-Andreas 在 #342 中澄清了 MuJoCo/Ant 在 v3（及更早版本）中缺少 use_contact_forces 的問題。

更新內容

感謝本次釋出的新貢獻者：@Matyasch, @DrRyanHuang, @nerdyespresso, @khoda81, @howardh, @mihaic, 和 @keyb0ardninja。

完整更新日誌: v0.27.1...v0.28.0

v0.27.1

釋出於 2023-01-20 - GitHub - PyPI

發行說明

修復的 Bug

新功能/改進

  • 由 @PaulMest 在 #235 中將 LunarLander-v2 step 效能提升了 1.5 倍以上。
  • 由 @nidhishs 在 #238 中為 StepAPICompatibility 包裝器添加了向量環境支援。
  • 由 @jjshoots 在 #241 中允許序列在特徵空間為 Box 時接受堆疊的 numpy 陣列。
  • 由 @pseudo-rnd-thoughts 在 #225 中改進了從外掛引發錯誤時的警告。
  • 由 @mgoulao 在 #257 中將更新日誌（發行說明）新增到了網站。
  • 由 @younik 在 #246 中實現了 RecordVideoV0。
  • 由 @PierreMardon 在 #267 中添加了當離散和多離散解壓失敗時的明確錯誤訊息。

文件更新

感謝 Gymnasium 的新貢獻者，如果你想參與進來，請加入我們的 Discord 伺服器。連結在 README 中。

完整更新日誌: 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。

一如既往，我們的開發路線圖 此處 公開可用，因此您可以關注我們未來的計劃。唯一仍在計劃中的重大破壞性更改是將選定的環境切換為使用硬體加速物理引擎，以及我們長期以來對向量 API 和內建包裝器進行大修的計劃。

本次釋出值得注意的是包含了一個全新的庫部分：gymnasium.experimental。我們正在新增新功能、包裝器和下面討論的功能性環境 API，供使用者測試和試用，以發現 Bug 並提供反饋。

新包裝器

這些新包裝器可在 gymnasium.experimental.wrappers 中訪問，完整列表請參見 https://gymnasium.llms.tw/main/api/experimental/。它們旨在替換 Gymnasium v0.30.0 中的包裝器，幷包含多項改進。

  • （正在進行中）支援任意複雜的觀測/動作空間。隨著強化學習的發展，動作和觀測空間變得越來越複雜，而當前的包裝器在實現時並未考慮到這一點。
  • 支援基於 Jax 的環境。隨著硬體加速環境（例如，用 Jax 編寫的 Brax 和類似的基於 PyTorch 的程式）的出現，NumPy 不再是編寫環境的唯一選擇。因此，這些升級將使用 Farama Foundation 開發的專案 Jumpy，它為 NumPy、Jax 以及未來 PyTorch 資料的大部分 NumPy 函式提供自動相容性。
  • 更多包裝器。像 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

其他重大更改

  • 由 @rodrigodelazcano 在 #112 中重構了 Mujoco 渲染機制，為 OpenGL 使用單獨的執行緒。移除 Viewer，轉而使用 MujocoRenderer，後者可用於離屏、人機及其他渲染模式。
  • 由 @pseudo-rnd-thoughts 在 #125 中為 gym.make(..., apply_env_compatibility=True) 添加了棄用警告，建議改用 gym.make("GymV22Environment", env_id="...")。
  • 由 @kad99kev 在 #124 中添加了 gymnasium.pprint_registry() 用於美觀地列印 Gymnasium 登錄檔。
  • 由 @pseudo-rnd-thoughts 在 #141 中將 Discrete.dtype 更改為 np.int64，以便樣本為 np.int64 而非 Python 整數。
  • 由 @pseudo-rnd-thoughts 在 #72 中添加了 OpenAI Gym v21 到 v26 的遷移指南。
  • 由 @pseudo-rnd-thoughts 在 #39 中為 core.py 中的 Env、Wrapper 等添加了完整的型別提示。
  • 由 @pseudo-rnd-thoughts 在 #37 中為 gymnasium.spaces 中的所有空間添加了完整的型別提示。
  • 由 @Markus28 在 #190 中使 play() 中的視窗可調整大小。
  • 由 @siddarth-c 在 #155 中添加了 REINFORCE 實現教程。

Bug 修復和文件更改

  • 由 @younik 在 #42 中移除了 VideoRecorder 包裝器中的自動關閉。
  • 由 @theo-brown 在 #74 中將 seeding.np_random 錯誤訊息更改為報告種子型別。
  • 由 @ikamensh 在 #83 中在 MujocoEnv 錯誤訊息中包含了形狀資訊。
  • 由 @tobirohrer 在 #89 中添加了美觀的特性/GitHub issue 表單。
  • 在 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
  • 添加了從扁平化空間中反扁平化樣本時的問題說明，由 @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

幕後更改

  • 文件版本控制，由 @mgoulao 提交於 #73
  • 在測試中添加了 Atari 環境，並移除了廢棄程式碼，由 @Markus28 提交於 #78
  • 修復了版本控制工作流中缺失的構建步驟，由 @mgoulao 提交於 #81
  • 對環境頁面進行了小改進，由 @mgoulao 提交於 #110
  • 更新了第三方環境文件，由 @pseudo-rnd-thoughts 提交於 #138
  • 更新了 docstring 以改進文件，由 @axb2035 提交於 #160
  • 在 CI 中測試核心依賴項，由 @pseudo-rnd-thoughts 提交於 #146
  • 更新並重新執行 pre-commit 鉤子以提高程式碼質量，由 @XuehaiPan 提交於 #179

v0.26.3

釋出於 2022-10-24 - GitHub - PyPI

發行說明

注意：ale-py (atari) 尚未更新到 Gymnasium。因此 pip install gymnasium[atari] 將會失敗，這將在 v0.27 中修復。在此期間，請使用 pip install shimmy[atari] 進行修復。

錯誤修復

  • 增加了 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)，這導致在向量環境中，最終步驟的資訊被覆蓋。現在，最終的觀察和資訊作為 “final_observation” 和 “final_info” 包含在 info 中。@pseudo-rnd-thoughts
  • 嘗試在未指定 render_mode 時新增警告 @younik
  • 更新了 Atari 預處理，使得包裝器可以被序列化 (pickled) @vermouth1992
  • GitHub CI 得到了加強，使其僅具有讀取許可權 @sashashura
  • 澄清並修復了 GraphInstance 中的拼寫錯誤 @ekalosak

v0.26.1

釋出於 2022-09-16 - GitHub - PyPI

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

此外，gym docs 倉庫已與新網站 https://gymnasium.llms.tw/ 合併。

v0.26.0: 首次釋出

釋出於 2022-09-13 - GitHub - PyPI

這是 Gymnasium 的首次釋出，它是 OpenAI Gym 的一個維護分支。

此版本與 Gym v0.26.0 完全相同，但專案名稱（Gymnasium）和行為準則除外。

閱讀 #12 檢視變更路線圖。