實用函式

種子設定

gymnasium.utils.seeding.np_random(seed: int | None = None) → tuple[Generator, int][源]

返回一個 NumPy 隨機數生成器 (RNG) 以及從輸入種子派生出的種子值。

如果 seed 為 None，則會生成一個隨機種子作為 RNG 的初始種子。這個隨機選擇的種子將作為元組的第二個值返回。

此函式在 reset() 中被呼叫，用於重置環境的初始 RNG。

引數：

seed – 用於建立生成器的種子

返回：

一個基於 NumPy 的隨機數生成器和生成器種子

丟擲：

錯誤 – 種子必須是非負整數

環境檢查

gymnasium.utils.env_checker.check_env(env: Env, warn: bool = None, skip_render_check: bool = False, skip_close_check: bool = False)[源]

檢查環境是否遵循 Gymnasium 的 API。

為確保環境“正確”實現，check_env 會檢查 observation_space 和 action_space 是否正確。此外，該函式會使用各種值呼叫 reset()、step() 和 render() 函式。

我們強烈建議使用者在環境構建後以及專案持續整合中呼叫此函式，以使環境與 Gymnasium 的 API 保持同步。

引數：

  • env – 將被檢查的 Gym 環境

  • warn – 已忽略，之前用於抑制特定警告

  • skip_render_check – 是否跳過渲染方法的檢查。預設為 False（對 CI 有用）

  • skip_close_check – 是否跳過關閉方法的檢查。預設為 False

視覺化

gymnasium.utils.play.play(env: Env, transpose: bool | None = True, fps: int | None = None, zoom: float | None = None, callback: Callable | None = None, keys_to_action: dict[tuple[str | int, ...] | str | int, ActType] | None = None, seed: int | None = None, noop: ActType = 0, wait_on_player: bool = False)[源]

允許使用者使用鍵盤操作環境。

如果在回合制環境中操作，請將 wait_on_player 設定為 True。

引數：

  • env – 用於操作的環境。

  • transpose – 如果為 True，則觀察輸出會被轉置。預設為 True。

  • fps – 每秒執行環境的最大步數。如果為 None（預設值），則使用 env.metadata["render_fps"]（如果環境未指定“render_fps”，則為 30）。

  • zoom – 放大觀察，zoom 量，應為正浮點數

  • callback –

    如果提供了回撥函式，它將在每一步之後執行。它接受以下輸入：

    • obs_t: 執行動作前的觀察

    • obs_tp1: 執行動作後的觀察

    • action: 執行的動作

    • rew: 獲得的獎勵

    • terminated: 環境是否已終止

    • truncated: 環境是否被截斷

    • info: 除錯資訊

  • keys_to_action –

    按鍵到執行動作的對映。支援不同的格式：按鍵組合可以表示為鍵的 Unicode 碼點元組、字元元組，或者字串，其中字串的每個字元代表一個鍵。例如，如果同時按下‘w’和空格應觸發動作 2，則 key_to_action 字典可能如下所示：

    >>> key_to_action = {
...    # ...
...    (ord('w'), ord(' ')): 2
...    # ...
... }

    或者像這樣：

    >>> key_to_action = {
...    # ...
...    ("w", " "): 2
...    # ...
... }

    或者像這樣：

    >>> key_to_action = {
...    # ...
...    "w ": 2
...    # ...
... }

    如果為 None，則使用該環境的預設 key_to_action 對映（如果提供）。

  • seed – 重置環境時使用的隨機種子。如果為 None，則不使用種子。

  • noop – 在沒有輸入按鍵或輸入的按鍵組合未知時使用的動作。

  • wait_on_player – 播放應等待使用者操作

示例

>>> import gymnasium as gym
>>> import numpy as np
>>> from gymnasium.utils.play import play
>>> play(gym.make("CarRacing-v3", render_mode="rgb_array"),  
...     keys_to_action={
...         "w": np.array([0, 0.7, 0], dtype=np.float32),
...         "a": np.array([-1, 0, 0], dtype=np.float32),
...         "s": np.array([0, 0, 1], dtype=np.float32),
...         "d": np.array([1, 0, 0], dtype=np.float32),
...         "wa": np.array([-1, 0.7, 0], dtype=np.float32),
...         "dw": np.array([1, 0.7, 0], dtype=np.float32),
...         "ds": np.array([1, 0, 1], dtype=np.float32),
...         "as": np.array([-1, 0, 1], dtype=np.float32),
...     },
...     noop=np.array([0, 0, 0], dtype=np.float32)
... )

以上程式碼在環境被封裝時也有效，因此它在驗證幀級預處理不會導致遊戲無法進行方面特別有用。

如果您希望在操作時繪製即時統計資料，可以使用 PlayPlot。以下是繪製過去 150 步獎勵的示例程式碼。

>>> from gymnasium.utils.play import PlayPlot, play
>>> def callback(obs_t, obs_tp1, action, rew, terminated, truncated, info):
...        return [rew,]
>>> plotter = PlayPlot(callback, 150, ["reward"])             
>>> play(gym.make("CartPole-v1"), callback=plotter.callback)
class gymnasium.utils.play.PlayPlot(callback: Callable, horizon_timesteps: int, plot_names: list[str])[源]

提供一個回撥函式，在使用 play() 時建立任意指標的即時圖表。

該類透過一個函式例項化，該函式接受關於單個環境轉換的資訊

  • obs_t: 執行動作前的觀察

  • obs_tp1: 執行動作後的觀察

  • action: 執行的動作

  • rew: 獲得的獎勵

  • terminated: 環境是否已終止

  • truncated: 環境是否被截斷

  • info: 除錯資訊

它應該返回一個從此資料計算出的指標列表。例如，該函式可能如下所示：

>>> def compute_metrics(obs_t, obs_tp, action, reward, terminated, truncated, info):
...     return [reward, info["cumulative_reward"], np.linalg.norm(action)]

PlayPlot 提供 callback() 方法，該方法會將其引數傳遞給該函式，並使用返回的值更新指標的即時圖表。

通常，此 callback() 將與 play() 結合使用，以檢視操作時指標如何演變。

>>> plotter = PlayPlot(compute_metrics, horizon_timesteps=200,                               
...                    plot_names=["Immediate Rew.", "Cumulative Rew.", "Action Magnitude"])
>>> play(your_env, callback=plotter.callback)
引數：

  • callback – 從環境轉換計算指標的函式

  • horizon_timesteps – 即時圖表使用的時間範圍

  • plot_names – 圖表標題列表

丟擲：

DependencyNotInstalled – 如果未安裝 matplotlib

callback(obs_t: ObsType, obs_tp1: ObsType, action: ActType, rew: float, terminated: bool, truncated: bool, info: dict)[源]

呼叫所提供的資料回撥函式並將資料新增到圖表的回撥函式。

引數：

  • obs_t – 時間步 t 的觀察

  • obs_tp1 – 時間步 t+1 的觀察

  • action – 動作

  • rew – 獎勵

  • terminated – 環境是否已終止

  • truncated – 環境是否被截斷

  • info – 來自環境的資訊

class gymnasium.utils.play.PlayableGame(env: Env, keys_to_action: dict[tuple[int, ...], int] | None = None, zoom: float | None = None)[源]

封裝一個環境，允許透過鍵盤輸入與環境互動。

引數：

  • env – 要操作的環境

  • keys_to_action – 鍵盤元組和動作值的字典

  • zoom – 是否放大環境渲染

process_event(event: Event)[源]

處理一個 PyGame 事件。

特別是，此函式用於跟蹤當前按下了哪些按鈕，並在 PyGame 視窗關閉時退出 play() 函式。

引數：

event – 要處理的事件

環境序列化

class gymnasium.utils.ezpickle.EzPickle(*args: Any, **kwargs: Any)[源]

透過其建構函式引數進行序列化和反序列化的物件。

示例

>>> class Animal: pass
>>> class Dog(Animal, EzPickle):
...    def __init__(self, furcolor, tailkind="bushy"):
...        Animal.__init__(self)
...        EzPickle.__init__(self, furcolor, tailkind)

當此物件被反序列化時，一個新的 Dog 將透過將提供的 `furcolor` 和 `tailkind` 傳遞給建構函式來構建。然而，哲學家們仍然不確定它是否還是同一只狗。

這通常只適用於封裝 C/C++ 程式碼的環境，例如 MuJoCo 和 Atari。

使用物件建構函式中的 args 和 kwargs 進行序列化。

儲存渲染影片

gymnasium.utils.save_video.save_video(frames: list, video_folder: str, episode_trigger: Callable[[int], bool] = None, step_trigger: Callable[[int], bool] = None, video_length: int | None = None, name_prefix: str = 'rl-video', episode_index: int = 0, step_starting_index: int = 0, save_logger: str | None = None, **kwargs)[源]

從渲染幀儲存影片。

此函式從渲染幀劇集列表中提取影片。

引數：

  • frames (List[RenderFrame]) – 用於組成影片的幀列表。

  • video_folder (str) – 錄製檔案將儲存的資料夾

  • episode_trigger – 接受整數並僅當應在此劇集開始錄製時返回 True 的函式

  • step_trigger – 接受整數並僅當應在此步驟開始錄製時返回 True 的函式

  • video_length (int) – 錄製劇集的長度。如果未指定，則錄製整個劇集。否則，會捕獲指定長度的片段。

  • name_prefix (str) – 將新增到錄製檔名的字首。

  • episode_index (int) – 當前劇集的索引。

  • step_starting_index (int) – 第一幀的步數索引。

  • save_logger – 是否記錄影片儲存進度，對於耗時較長的影片很有用，使用“bar”啟用。

  • **kwargs – 將傳遞給 moviepy 的 ImageSequenceClip 的關鍵字引數。您需要指定 fps 或 duration。

示例

>>> import gymnasium as gym
>>> from gymnasium.utils.save_video import save_video
>>> env = gym.make("FrozenLake-v1", render_mode="rgb_array_list")
>>> _ = env.reset()
>>> step_starting_index = 0
>>> episode_index = 0
>>> for step_index in range(199): 
...    action = env.action_space.sample()
...    _, _, terminated, truncated, _ = env.step(action)
...
...    if terminated or truncated:
...       save_video(
...          frames=env.render(),
...          video_folder="videos",
...          fps=env.metadata["render_fps"],
...          step_starting_index=step_starting_index,
...          episode_index=episode_index
...       )
...       step_starting_index = step_index + 1
...       episode_index += 1
...       env.reset()
>>> env.close()
gymnasium.utils.save_video.capped_cubic_video_schedule(episode_id: int) → bool[源]

預設劇集觸發器。

此函式將在劇集索引 \(\{0, 1, 4, 8, 27, ..., k^3, ..., 729, 1000, 2000, 3000, ...\}\) 處觸發錄製。

引數：

episode_id – 劇集編號

返回：

是否應用影片時間表編號

舊步長 API 到新步長 API 相容性

gymnasium.utils.step_api_compatibility.step_api_compatibility(step_returns: tuple[ObsType | ndarray, SupportsFloat | ndarray, bool | ndarray, bool | ndarray, dict | list] | tuple[ObsType | ndarray, SupportsFloat | ndarray, bool | ndarray, dict | list], output_truncation_bool: bool = True, is_vector_env: bool = False) → tuple[ObsType | ndarray, SupportsFloat | ndarray, bool |ndarray, bool |ndarray, dict | list] | tuple[ObsType | ndarray, SupportsFloat | ndarray, bool |ndarray, dict | list][源]

根據 output_truncation_bool 指定的 API 轉換步長返回值的功能。

Done（舊）步長 API 指的是 step() 方法返回 (observation, reward, done, info)。Terminated Truncated（新）步長 API 指的是 step() 方法返回 (observation, reward, terminated, truncated, info)（有關 API 更改的詳細資訊，請參閱文件）。

引數：

  • step_returns (tuple) – step() 返回的項。可以是 (obs, rew, done, info) 或 (obs, rew, terminated, truncated, info)

  • output_truncation_bool (bool) – 輸出是返回兩個布林值（新 API）還是一個布林值（舊 API）（預設為 True）

  • is_vector_env (bool) – step_returns 是否來自向量環境

返回：

step_returns (tuple) – 根據 output_truncation_bool，它可以返回 (obs, rew, done, info) 或 (obs, rew, terminated, truncated, info)

示例

此函式可用於確保在具有衝突 API 的步長介面中的相容性。例如，如果環境是用舊 API 編寫的，封裝器是用新 API 編寫的，並且最終步長輸出需要是舊 API。

>>> import gymnasium as gym
>>> env = gym.make("CartPole-v0")
>>> _, _ = env.reset()
>>> obs, reward, done, info = step_api_compatibility(env.step(0), output_truncation_bool=False)
>>> obs, reward, terminated, truncated, info = step_api_compatibility(env.step(0), output_truncation_bool=True)

>>> vec_env = gym.make_vec("CartPole-v0", vectorization_mode="sync")
>>> _, _ = vec_env.reset()
>>> obs, rewards, dones, infos = step_api_compatibility(vec_env.step([0]), is_vector_env=True, output_truncation_bool=False)
>>> obs, rewards, terminations, truncations, infos = step_api_compatibility(vec_env.step([0]), is_vector_env=True, output_truncation_bool=True)
gymnasium.utils.step_api_compatibility.convert_to_terminated_truncated_step_api(step_returns: tuple[ObsType | ndarray, SupportsFloat | ndarray, bool | ndarray, dict | list] | tuple[ObsType | ndarray, SupportsFloat | ndarray, bool | ndarray, bool | ndarray, dict| list], is_vector_env=False) → tuple[ObsType | ndarray, SupportsFloat | ndarray, bool |ndarray, bool | ndarray, dict | list][源]

無論輸入 API 是什麼，都將步長返回值轉換為新步長 API 的函式。

引數：

  • step_returns (tuple) – step() 返回的項。可以是 (obs, rew, done, info) 或 (obs, rew, terminated, truncated, info)

  • is_vector_env (bool) – step_returns 是否來自向量環境

gymnasium.utils.step_api_compatibility.convert_to_done_step_api(step_returns: tuple[ObsType | ndarray, SupportsFloat | ndarray, bool | ndarray, bool | ndarray, dict | list] | tuple[ObsType | ndarray, SupportsFloat | ndarray, bool| ndarray, dict | list], is_vector_env: bool = False) → tuple[ObsType | ndarray, SupportsFloat | ndarray, bool |ndarray, dict | list][源]

無論輸入 API 是什麼，都將步長返回值轉換為舊步長 API 的函式。

引數：

  • step_returns (tuple) – step() 返回的項。可以是 (obs, rew, done, info) 或 (obs, rew, terminated, truncated, info)

  • is_vector_env (bool) – step_returns 是否來自向量環境

執行時效能基準測試

有時需要測量環境的執行時效能，並確保沒有效能退化發生。這些測試需要手動檢查其輸出結果。

gymnasium.utils.performance.benchmark_step(env: Env, target_duration: int = 5, seed=None) → float[源]

衡量環境步長執行時效能的基準測試。

示例用法：

`py env_old = ... old_throughput = benchmark_step(env_old) env_new = ... new_throughput = benchmark_step(env_old) slowdown = old_throughput / new_throughput `

引數：

  • env – 要進行基準測試的環境。

  • target_duration – 基準測試的持續時間（以秒為單位）（注意：它會略微超出）。

  • seed – 對環境和取樣的動作進行種子設定。

返回：平均每秒步數。

gymnasium.utils.performance.benchmark_init(env_lambda: Callable[[], Env], target_duration: int = 5, seed=None) → float[源]

衡量初始化時間和首次重置時間的基準測試。

引數：

  • env_lambda – 初始化環境的函式。

  • target_duration – 基準測試的持續時間（以秒為單位）（注意：它會略微超出）。

  • seed – 對環境的首次重置進行種子設定。

gymnasium.utils.performance.benchmark_render(env: Env, target_duration: int = 5) → float[源]

衡量 render() 時間的基準測試。

注意：不適用於 render_mode=’human’ :param env: 要進行基準測試的環境（注意：必須可渲染）。 :param target_duration: 基準測試的持續時間（以秒為單位）（注意：它會略微超出）。