實用工具函數

Seeding

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

從輸入的 seed 返回 NumPy 隨機數生成器 (RNG) 以及 seed 值。

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

此函數在 reset() 中調用，以重置環境的初始 RNG。

參數:

seed – 用於建立生成器的 seed

返回:

基於 NumPy 的隨機數生成器和生成器 seed

引發:

Error – Seed 必須是非負整數

環境檢查

gymnasium.utils.env_checker.check_env(env: Env, warn: bool | None = 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 – 是否跳過 render 方法的檢查。預設為 False（適用於 CI）

  • skip_close_check – 是否跳過 close 方法的檢查。預設為 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 –

    如果提供了 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 – 重置環境時使用的隨機 seed。如果為 None，則不使用 seed。

  • 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])[來源]

提供一個 callback，以在使用 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)[來源]

調用提供的資料 callback 並將資料新增到繪圖的 callback。

參數:

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

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

這通常僅適用於包裝 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 的 kwargs。您需要指定 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 – 劇集編號

返回:

是否應用影片排程編號

新舊 Step API 相容性

gymnasium.utils.step_api_compatibility.step_api_compatibility(step_returns: TerminatedTruncatedStepType | DoneStepType, output_truncation_bool: bool = True, is_vector_env: bool = False) → TerminatedTruncatedStepType | DoneStepType[來源]

將 step 返回值轉換為 output_truncation_bool 指定的 API 的函數。

Done（舊）step API 指的是 step() 方法返回 (observation, reward, done, info)。Terminated Truncated（新）step 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）或一個（舊）（預設為 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: DoneStepType | TerminatedTruncatedStepType, is_vector_env=False) → TerminatedTruncatedStepType[source]

將步驟回傳值轉換為新步驟 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: TerminatedTruncatedStepType | DoneStepType, is_vector_env: bool = False) → DoneStepType[source]

將步驟回傳值轉換為舊步驟 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[source]

一個基準測試，用於測量環境步驟的執行時期效能。

使用範例

`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[source]

一個基準測試，用於測量初始化時間和首次重置。

參數:

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

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

  • seed – 為環境的首次重置設定種子。

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

一個基準測試，用於測量 render() 的時間。

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