实用函数

种子设置

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: 基准测试的持续时间（以秒为单位）（注意：它会略微超出）。