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 中，我們新增了空間遮罩，space.sample(mask=...)，以邏輯方式遮罩空間中可能的樣本。#1310 為每個空間新增了機率遮罩，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 提供的具有機率遮罩的空間採樣 (#1310)
  • 由 @DavidPL1 新增 rgb + 深度渲染至 mujoco (#1229)
  • 由 @amacati 新增 JaxToNumpy、JaxToTorch 和 NumpyToTorch 的渲染支援 (#1306)
  • 由 @amacati 新增對 dlpack API 的完整支援 (#1299)
  • 由 @sparisi 啟用 StickyAction 封裝器以重複舊動作超過 1 步 (#1240)
  • 由 @howardh 為單一 obs/動作空間引數新增 wrappers.vector.TransformObs/Action 支援 (#1288)
  • 由 @duburcqa 改進封裝器的 'set_wrapper_attr'，以修改變數的更新方式 (#1294)
  • 由 @li-plus 允許 AtariPreprocessing 支援非正方形觀察 (#1312)
  • 由 @pseudo-rnd-thoughts 改進 Wrapper 和 VectorWrapper 錯誤檢查 (#1260)

錯誤修正

文件變更

  • 由 @artemmiyy 修正了 blackjack 中取樣值的錯字，將 2-9 更正為 2-10 (#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 包含一個範例向量 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 類別。請參閱 向量封裝器 頁面以取得新資訊。

為了提高向量環境的效率，自動重置是一項常見功能，允許子環境在重置所有子環境之前重置，而無需所有子環境都完成。先前在 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 字典）以及必須提取最終觀察才能正確訓練智能體的煩惱，例如 範例。因此，在 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，允許使用者在環境堆疊中的任何位置設定變數（如果該變數已存在）。先前，這是不可能的，使用者只能修改環境堆疊“頂層”封裝器中的變數，重要的是不能修改實際環境本身。

封裝器

先前，某些封裝器可以同時支援環境和向量環境，但是，這並未標準化，並且不清楚哪些封裝器支援和不支援向量環境。對於 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 的使用者帶來問題。因此，我們停用了 v4 環境，並使用 mujoco>= 3 更新為 MuJoCo v5 中的模型，該模型產生更符合預期的行為，例如 v4 和 mujoco< 3 (#1019)。

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

  • Lunar Lander 版本從 v2 升級至 v3，原因在於修正了兩個錯誤。第一個錯誤修正了環境的決定性，起因是世界物件在重置時並未完全銷毀，導致在特定情況下出現非決定性 (#979)。第二個錯誤是風力生成（預設為關閉）並未在每次重置時隨機生成，因此，我們已更新此設定，以獲得 episode 之間的統計獨立性 (#959)。

  • CarRacing 版本從 v2 升級至 v3，變更了環境結束的方式，當 agent 完成賽道時，環境將會終止 (terminate) 而非截斷 (truncate)。

  • 我們已移除 pip install "gymnasium[accept-rom-license]"，因為 ale-py>=0.9 現在已包含 roms，表示使用者不再需要使用 autoroms 分開安裝 atari roms。

額外的錯誤修正

  • spaces.Box 允許低值和高值超出 dtype 的範圍，這可能會導致一些非常奇怪的邊緣情況，這些情況很難被 @pseudo-rnd-thoughts 偵測到 (#774)
  • 限制 gymnasium[mujoco-py] 的 cython 版本，因為 cython==3 的問題，由 @pseudo-rnd-thoughts 修正 (#616)
  • 修正使用自訂寬度值時 mujoco 渲染的問題，由 @logan-dunbar 修正 (#634)
  • 修正環境檢查器以正確報告無限邊界，由 @chrisyeh96 修正 (#708)
  • 修正 register(kwargs) 的類型提示，從 **kwargs 改為 kwargs: dict | None = None，由 @younik 修正 (#788)
  • 修正在 AsyncVectorEnv 中註冊自訂環境的問題，由 @RedTachyon 修正 (#810)
  • 移除 v4+ MuJoCo 環境的 mujoco-py 導入錯誤，由 @MischaPanch 修正
    (#934)
  • 修正 Tuple 和 Dict spaces 的共享記憶體讀取問題 (#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。

收集 seeding 值

可以使用 None 同時為環境和 spaces 設定 seed，以使用隨機初始 seed 值，但無法知道這些初始 seed 值是什麼。我們已在 #1033 和 #889 中解決了 Space.seed 和 reset.seed 的問題。對於 Space.seed，我們已將回傳類型變更為針對每個 space 進行特製化，以便以下程式碼適用於所有 spaces。

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 不相容，原因是錯誤修正在 agent 必須推動的方塊中發現模型密度為空氣密度。這顯然開始對使用 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)。第二個錯誤是風力生成（預設為關閉）並未在每次重置時隨機生成，因此，我們已更新此設定，以獲得 episode 之間的統計獨立性 (#959)。

Box 範例

發現 spaces.Box 允許低值和高值超出 dtype 的範圍 (#774)，這可能會導致一些非常奇怪的邊緣情況，這些情況很難被偵測到。我們希望這些變更能改善偵錯和偵測 space 的無效輸入，但是，如果您的環境因此類問題而產生問題，請告訴我們。

錯誤修正

  • 更新 CartPoleVectorEnv 以使用新的 autoreset API (#915)
  • 修正了來自新 autoreset api 的 wrappers.vector.RecordEpisodeStatistics episode 長度計算 (#1018)
  • 移除 v4+ MuJoCo 環境的 mujoco-py 導入錯誤 (#934)
  • 修正 make_vec(**kwargs) 未傳遞至 vector entry point envs 的問題 (#952)
  • 修正 Tuple 和 Dict spaces 的共享記憶體讀取問題 (#941)
  • 修正 windows 的 Multidiscrete.from_jsonable 問題 (#932)
  • 移除 play 渲染正規化 (#956)

新功能

  • 新增 Python 3.12 支援
  • 新增一個新的 OneOf space，提供 spaces 的互斥聯集 (#812)
  • 更新 Dict.sample 以使用標準 Python dicts 而非 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）認為 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) 可能為 true，儘管兩者的行為不同），以及最終的 wrapper（某些 Gym 和 Gymnasium wrapper 支援向量環境，但沒有明確或一致的 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 的 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 類別。請參閱 向量封裝器 頁面以取得新資訊。

為了提高向量環境的效率，自動重設是一個常見的功能，允許子環境在不需要所有子環境都完成後才重設它們的情況下重設。先前在 Gym 和 Gymnasium 中，自動重設是在環境 episode 結束的同一個步驟中完成的，因此最終的觀察和資訊將儲存在步驟的 info 中，即 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 的麻煩，例如 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)

最後，我們改進了 AsyncVectorEnv.set_attr 和 SyncVectorEnv.set_attr 函式，以使用 Wrapper.set_wrapper_attr，允許使用者在環境堆疊中的任何位置設定變數（如果該變數已存在）。先前，這是不可能的，使用者只能修改環境堆疊中“頂層” 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 作為等效函式，用於在環境堆疊中的任何位置設定變數（如果該變數已存在）；僅在頂層 wrapper（或環境）中設定變數。

最重要的是，我們已移除、重新命名和新增了以下列出的幾個封裝器。

  • 已移除的封裝器
    • monitoring.VideoRecorder - 替換封裝器是 RecordVideo
    • StepAPICompatibility - 我們期望所有 Gymnasium 環境都使用 terminated / truncated step API，因此，使用者不應需要 StepAPICompatibility wrapper。 Shimmy 包含一個相容性環境，用於轉換 gymnasium 的 gym-api 環境。
  • 已重新命名的封裝器（我們希望使封裝器的命名一致。因此，我們已從所有封裝器中移除“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 的替代定義，它更接近 Markov Decision Process 定義，向使用者公開更多函式，包括觀察、獎勵和終止函式，以及環境的原始狀態作為單一物件。

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)
  • 修正使用自訂寬度值時 mujoco 渲染的問題，由 @logan-dunbar 修正 (#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)
  • 在 MuJoCo 渲染中新增更多關於離螢幕尺寸和場景幾何圖形的控制，由 @guyazran 實作 (#731)
  • 新增支援以處理 JaxToNumpy、JaxToTorch 和 NumpyToTorch 中的 NamedTuples，由 @RogerJL (#789) 和 @pseudo-rnd-thoughts (#811) 共同完成
  • 新增 padding_type 參數至 FrameSkipObservation，以選擇 padding observation，由 @jamartinh 實作 (#830)
  • 新增渲染檢查至 check_environments_match，由 @Kallinteris-Andreas 實作 (#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 的支援，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 wrappers 中移除 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 wrapper，由 @LucasAlegre 在 #561 中貢獻
  • 新增 check_environments_match 函式，用於檢查兩個環境是否相同，由 @Kallinteris-Andreas 在 #576 中貢獻
  • 新增效能偵錯工具，utils/performance.py，由 @Kallinteris-Andreas 在 #583 中貢獻
  • 新增基於 Jax 的懸崖漫步環境，由 @balisujohn 在 #407 中貢獻
  • MuJoCo
  • 實驗性
    • 在 gymnasium.experimental.wrappers 中新增已棄用的 wrapper 錯誤，由 @charraut 在 #341 中貢獻
    • 為 RecordVideoV0 新增 fps 參數，以支援覆寫環境內部 render_fps 值的自訂 fps 值，由 @younik 在 #503 中貢獻
    • 新增實驗性向量 wrappers，用於 lambda 觀察、動作和獎勵 wrappers，由 @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 中貢獻
  • 修正實驗性向量環境和 wrappers 中的幾個問題，由 @pseudo-rnd-thoughts 在 #516 中貢獻
  • 影片錄製器 wrapper
    • 修正 VideoRecorder 在 reset 時清空 recorded_frames 而不是 frames 的問題，由 @voidflight 在 #518 中貢獻
    • 移除 VideoRecorder.close 中的 Env.close，由 @qgallouedec 在 #533 中貢獻
    • 修正 VideoRecorder 和 RecordVideoV0 以移動 import moviepy，以便 __del__ 不會引發 AttributeErrors，由 @pseudo-rnd-thoughts 在 #553 中貢獻
  • Mujoco
    • 移除 Hopper-v4 的舊版渲染 API 函式，由 @Kallinteris-Andreas 在 #588 中貢獻
    • 修復在關閉渲染時發生的 TypeError，由 @sonelu 於 (#440) 中修復
    • 修復 MujocoEnv 的 _step_mujoco_simulation 函數中錯誤的 nstep，由 @xuanhien070594 於 #424 中修復
    • 允許致動器控制的數量與動作空間不同，由 @reginald-mclean 於 #604 中完成

文件更新

完整變更日誌：v0.28.1...v0.29.0

v0.28.1

於 2023-03-25 發布 - GitHub - PyPI

v0.28.1 發行說明

小型緊急發行版本，以修復數個問題

  • 修復 gymnasium/__init__.py 中的 gymnasium.vector，因為它未被導入 #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 現在可以建立完整的環境堆疊，包括 wrappers，以便訓練庫或離線資料集可以指定環境使用的所有參數和 wrappers。對於大多數標準用法 (gym.make(”EnvironmentName-v0”))，除了某些相當罕見的情況（即 env.spec 和 env.unwrapped.spec 返回不同的 specs）之外，這將是向後相容的，這是一個重大變更。請參閱再現性詳細資訊章節以取得更多資訊。
在 v0.27 中，我們新增了 experimental 資料夾，以便我們開發幾個新功能（wrappers 和硬體加速環境）。我們引入了一個新的實驗性 VectorEnv 類別。此類別不繼承標準 Env 類別，並且將允許更有效率的平行化功能。我們計劃在接下來的幾個月內，在幾個小版本中改進實作並新增基於向量的 wrappers。
此外，我們優化了模組載入，以便僅在使用者導入需要 PyTorch 或 Jax 的 wrappers 時才載入它們，而不是在 import gymnasium 時載入。

再現性詳細資訊

在先前的版本中，Gymnasium 支援 gym.make(spec)，其中 spec 是來自 gym.spec(str) 或 env.spec 的 EnvSpec，並且與基於字串的 gym.make(“”) 完全相同。在這兩種情況下，都無法指定應應用於環境的其他 wrappers。在此版本中，我們將 additional_wrappers 新增至 EnvSpec，以指定應用於基礎環境的 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`

為了支援此類型的重建，wrappers 必須繼承自 gym.utils.RecordConstructorUtils，以允許 gym.make 知道使用哪些參數來建立 wrapper。Gymnasium 已為所有內建 wrappers 實作了此功能，但對於外部專案，應將其新增至每個 wrapper。為此，請在 wrapper 建構函數的第一行呼叫 gym.utils.RecordConstructorUtils.__init__(self, …)，並使用與傳遞給 wrapper 建構函數相同的 l 關鍵字參數，但 env 除外。有關範例，請參閱 Atari Preprocessing wrapper
如需更詳細的討論，請參閱原始 PR - #292 和 #355

其他主要變更

  • 在 Gymnasium v0.26 中，新增了 GymV22Compatibility 環境以支援 Gymnasium 中的基於 Gym 的環境。但是，名稱不正確，因為 env 支援 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 僅在使用者載入特定 wrappers 時才載入。#323
  • 在 v0.26 中，我們為 Wrapper 新增了參數，以允許為 wrapper 及其子環境指定不同的觀察和動作類型。但是，這引發了 pyright 和 mypy 的類型問題，現在已通過 Wrapper 具有四個泛型參數 [ObsType, ActType, WrappedEnvObsType, WrappedEnvActType] 來修復。#337
  • 在 v0.25 和 0.v26 中，引入了幾種新的空間類型，Text、Graph 和 Sequence，但是向量實用函數未更新以支援這些空間。已將對這些空間的支援新增至實驗性向量空間實用函數：batch_space、concatenate、iterate 和 create_empty_array。#223
  • 由於缺乏測試，實驗性有狀態觀察 wrappers (FrameStackObservation、DelayObservation 和 TimeAwareObservation) 未如預期般運作。這些 wrappers 現在已修復，並已新增測試。#224

次要變更

  • 允許停用和啟用 NormalizeX wrappers 的統計資訊，以便在評估期間使用，由 @raphajaner 於 #268 中完成
  • 修復 lunar_lander.py 中的 AttributeError，由 @DrRyanHuang 於 #278 中完成
  • 新增 docstring 測試 (doctest)，以便 docstring 與 @valentin-cnt 在 #281 中的實作相符
  • 類型提示修復並新增 __all__ dunder，由 @howardh 於 #321 中完成
  • 修復 gymnasium/spaces 中的類型提示錯誤，由 @valentin-cnt 在 #327 中完成
  • 更新實驗性向量共享記憶體實用函數，由 @pseudo-rnd-thoughts 於 #339 中完成
  • 將 Gymnasium Notices 變更為 Farama Notifications，由 @jjshoots 於 #332 中完成
  • 新增基於 Jax 的 Blackjack 環境，由 @balisujohn 於 #338 中完成

文件變更

  • 修正在文件中對 MultiBinary 和 MultiDiscrete 類別的參考，由 @Matyasch 於 #279 中完成
  • 新增 Comet 整合，由 @nerdyespresso 於 #304 中完成
  • 更新 atari 文件，由 @pseudo-rnd-thoughts 於 #330 中完成
  • 記錄 Box 整數邊界，由 @mihaic 於 #331 中完成
  • 新增 docstring 解析器，以移除 Gymnasium 網站中的重複內容，由 @valentin-cnt 在 #329 中完成
  • 修正在基本用法頁面中的文法錯誤，由 @keyb0ardninja 在 #333 中完成
  • 更新 docs/README.md 以連結到新的 CONTRIBUTING.md 文件 (用於文件)，由 @mgoulao 於 #340 中完成
  • 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

發行說明

錯誤修復

  • 將 np.bool8 替換為 np.bool_，以解決 numpy 1.24 的棄用警告，由 @pseudo-rnd-thoughts 於 #221 中完成
  • 移除 shimmy 作為核心依賴項，由 @pseudo-rnd-thoughts 於 #272 中完成
  • 修復 ResizeObservation 對於 2 維觀察的靜默錯誤，由 @ianyfan 於 #230 和 @RedTachyon 於 #254 中完成
  • 將環境檢查器斷言變更為警告，由 @jjshoots 於 #215 中完成
  • 修正當在未使用中繼資料渲染模式下使用渲染模式時發生的 make 錯誤，由 @pseudo-rnd-thoughts 在 #216 中完成
  • 更新額外依賴項的提示訊息，由 @XuehaiPan 在 #250 中完成
  • 修正 AsyncVectorEnv.reset 的回傳類型，由 @younik 在 #252 中完成
  • 更新 jumpy 錯誤訊息，以明確指出 pip install 指令應為 jax-jumpy，由 @pseudo-rnd-thoughts 在 #255 中完成
  • 修正 callable 的類型註解為 Callable，由 @ianyfan 在 #259 中完成
  • 修正實驗性的正規化獎勵包裝器，由 @rafaelcp 在 #277 中完成

新功能/改進

  • 將 LunarLander-v2 step 效能提升 >1.5 倍，由 @PaulMest 在 #235 中完成
  • 為 StepAPICompatibility 包裝器新增向量環境支援，由 @nidhishs 在 #238 中完成
  • 允許序列接受堆疊的 np 陣列 (如果特徵空間為 Box)，由 @jjshoots 在 #241 中完成
  • 改進從外掛程式引發錯誤時的警告訊息，由 @pseudo-rnd-thoughts 在 #225 中完成
  • 將變更日誌 (發行說明) 新增至網站，由 @mgoulao 在 #257 中完成
  • 實作 RecordVideoV0，由 @younik 在 #246 中完成
  • 當取消扁平化 discrete 和 multidiscrete 失敗時，新增明確的錯誤訊息，由 @PierreMardon 在 #267 中完成

文件更新

  • 將 doctest 新增至 CI 並修正 docstrings 中所有現有的錯誤，由 @valentin-cnt 在 #274 中完成
  • 新增使用 A2C 的向量化環境教學課程。由 @till2 在 #234 中完成
  • 修正 MuJoCo.Humanoid 動作描述，由 @Kallinteris-Andreas 在 #206 中完成
  • Ant use_contact_forces 觀測和獎勵 DOC，由 @Kallinteris-Andreas 在 #218 中完成
  • MuJoCo.Reacher-v4 文件修正，由 @Kallinteris-Andreas 在 #219 中完成
  • 在遷移指南中提及截斷，由 @RedTachyon 在 #105 中完成
  • docs(教學課程)：修正環境建立連結，由 @lpizzinidev 在 #244 中完成
  • Mujoco/Hooper 文件小錯誤修正，由 @Kallinteris-Andreas 在 #247 中完成
  • 在 A2C 教學課程中新增註解，說明 convolve 的作用，由 @metric-space 在 #264 中完成
  • 修正 README.md 中的環境版本控制，由 @younik 在 #270 中完成
  • 新增教學課程圖庫，由 @mgoulao 在 #258 中完成

感謝 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 (如下所述)，供使用者測試和試用，以尋找錯誤並提供意見回饋。

新的包裝器

這些新的包裝器可在 gymnasium.experimental.wrappers 中存取，完整列表請參閱 https://gymnasium.dev.org.tw/main/api/experimental/，旨在取代 gymnasium v0.30.0 中的包裝器，並包含多項改進

  • (工作中) 支援任意複雜的觀測 / 動作空間。隨著 RL 的發展，動作和觀測空間變得越來越複雜，而目前的包裝器在實作時並未考慮到這一點。
  • 支援基於 Jax 的環境。隨著硬體加速環境 (例如 Brax) 以 Jax 和類似的基於 PyTorch 的程式撰寫，NumPy 不再是撰寫環境的唯一選擇。因此，這些升級將使用 Jumpy，這是 Farama Foundation 開發的專案，旨在為大量 NumPy 函數提供 NumPy、Jax 以及未來 PyTorch 資料的自動相容性。
  • 更多包裝器。像 Supersuit 這樣的專案旨在為 RL 帶來更多包裝器，但是，許多使用者並不知道這些包裝器，因此我們計畫將這些包裝器移至 Gymnasium 中。如果我們遺漏了上面列表中常見的包裝器，請建立 issue，我們有興趣將其新增進來。
  • 版本控制。與環境一樣，包裝器的實作細節可能會導致代理程式效能的變化。因此，我們建議為所有包裝器新增版本號碼，例如 LambaActionV0。我們預期這些版本號碼不會經常變更，並且其作用將類似於環境版本號碼。這應確保所有使用者都知道何時重大變更可能會影響您的代理程式在環境和包裝器上的效能。此外，我們希望這將有助於提高未來 RL 的可重現性，這對於學術界至關重要。
  • 在 v28 中，我們的目標是重寫 VectorEnv 以使其不繼承自 Env，因此將提供新的向量化版本的包裝器。

核心開發人員： @gianlucadecola、 @RedTachyon、 @pseudo-rnd-thoughts

功能性 API

Env 類別為環境的撰寫提供了一個非常通用的結構，允許程式結構具有高度的彈性。但是，這限制了有效向量化環境、劃分環境程式碼等的能力。因此，gymnasium.experimental.FuncEnv 為環境實作提供了更嚴格的結構，針對環境實作的每個階段都使用無狀態函數。此類別不繼承自 Env，並且需要一個轉譯 / 相容性類別才能執行此操作。我們已經提供了一個 FuncJaxEnv，用於將基於 jax 的 FuncEnv 轉換為 Env。我們希望這將有助於提高環境實作的可讀性，並為向量化程式碼的使用者帶來潛在的速度提升。

此 API 非常實驗性，因此未來可能會進行變更。我們有興趣聽取嘗試使用該 API 的使用者的意見回饋，我們認為這將特別引起探索 RL 規劃、基於模型的 RL 以及修改獎勵等環境函數的使用者的興趣。

核心開發人員： @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 整數，由 @pseudo-rnd-thoughts 在 #141 中完成
  • 新增 OpenAI Gym v21 至 v26 的遷移指南，由 @pseudo-rnd-thoughts 在 #72 中完成
  • 為 core.py 中的 Env、Wrapper 等新增完整的類型提示，由 @pseudo-rnd-thoughts 在 #39 中完成
  • 為 gymnasium.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 中完成
  • 修正 docstring 並更新經典控制環境的動作空間描述，由 @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 中完成
  • 更新包裝器文件，由 @Markus28 在 #173 中完成
  • 更新空間文件格式，由 @Markus28 在 #174 中完成
  • 針對 FrozenLake，在隨機地圖生成中新增種子設定，由 @kir0ul 在 #139 中完成
  • 為從扁平化空間取消扁平化樣本時的問題新增註解，由 @rusu24edward 在 #164 中完成
  • 將 pusher 環境頁面包含到網站中，由 @axb2035 在 #171 中完成
  • 在 AsyncVectorEnv 的 step_wait 中加入檢查成功狀態，然後再由 @aaronwalsman 在 #178 中分割結果。
  • 由 @Kallinteris-Andreas 在 #183 中加入 MuJoCo.Ant-v4.use_contact_forces 的文件。
  • 由 @cool-RR 在 #184 中修正 README.md 中的錯字。
  • 由 @Kallinteris-Andreas 在 #186 中加入 MuJoCo.Ant v4 更新日誌的文件。
  • 由 @Kallinteris-Andreas 在 #208 中修正文件中 MuJoCo.Ant 的動作順序。
  • 由 @cool-RR 在 #205 中為整個程式碼庫加入 raise-from 例外。

幕後變更

v0.26.3

於 2022-10-24 發布 - GitHub - PyPI

發行說明

注意：ale-py (atari) 尚未更新至 Gymnasium。因此，pip install gymnasium[atari] 將會失敗，此問題將在 v0.27 中修正。在此期間，請使用 pip install shimmy[atari] 作為暫時的解決方案。

錯誤修正

  • 由 @RedTachyon 在 #61 中加入 Gym-Gymnasium 相容性轉換器，讓使用者可以在 Gymnasium 中使用 Gym 環境。
  • 由 @RedTachyon 在 #35 中修改 HumanRendering 和 RenderCollection wrappers 中的 metadata 以擁有正確的 metadata。
  • 由 @DavidSlayback 在 #31 中簡化 EpisodeStatisticsRecorder wrapper。
  • 由 @olipinski 在 #55 中修正 MultiDiscrete.flatten() 中的整數溢位問題。
  • 由 @Kallinteris-Andreas 在 #70 中重新加入為 Mujoco 環境指定 XML 檔案的功能。

文件變更

完整變更日誌： v0.26.2...v0.26.3

感謝新的貢獻者

v0.26.2

於 2022-10-05 發布 - GitHub - PyPI

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

錯誤修正

  • 由於 reset 現在會傳回 (obs, info)，這導致在向量環境中，最後一步的 info 會被覆寫。現在，最終的 observation 和 info 包含在 info 中，名稱為 "final_observation" 和 "final_info" @pseudo-rnd-thoughts
  • 當嘗試在未指定 render_mode 的情況下進行渲染時，新增警告訊息 @younik
  • 更新 Atari Preprocessing，使 wrapper 可以被 pickled @vermouth1992
  • Github CI 已加強安全性，使 CI 僅具有讀取權限 @sashashura
  • 釐清並修正 GraphInstance 中的錯字 @ekalosak

v0.26.1

於 2022-09-16 發布 - GitHub - PyPI

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

此外，gym docs repo 已與新網站 https://gymnasium.dev.org.tw/ 合併。

v0.26.0：初始版本

於 2022-09-13 發布 - GitHub - PyPI

這是 Gymnasium 的第一個版本，Gymnasium 是 OpenAI Gym 的維護分支。

此版本與 Gym v0.26.0 完全相同，除了專案名稱 (Gymnasium) 和行為準則。

閱讀 #12 以了解變更的路線圖。