实用函数

播种

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

返回一个 NumPy 随机数生成器 (RNG) 以及从输入种子生成的种子值。

如果 seed 为 None，则会生成一个随机种子作为 RNG 的初始种子。此随机选择的种子将作为元组的第二个值返回。

此函数在 reset() 中被调用，以重置环境的初始 RNG。

参数:

seed – 用于创建生成器的种子

返回:

基于 NumPy 的随机数生成器和生成器种子

引发:

Error – 种子必须是非负整数

环境检查

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

检查环境是否遵循 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)[source]

允许用户使用键盘玩游戏环境。

如果在回合制环境中玩游戏，请将 wait_on_player 设置为 True。

参数:

  • env – 用于玩游戏的环境。

  • transpose – 如果为 True，则观察结果的输出将被转置。默认为 True。

  • fps – 每秒执行的环境步数的最大值。如果为 None（默认值），则使用 env.metadata["render_fps""]（或 30，如果环境未指定“render_fps”）。

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

提供一个回调函数，用于在使用 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)[source]

调用提供的 data 回调并将数据添加到绘图的回调。

参数:

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

包装一个环境，允许使用键盘输入与环境交互。

参数:

  • env – 要玩的游戏环境

  • keys_to_action – 键盘元组和动作值的字典

  • zoom – 是否放大环境渲染

process_event(event: Event)[source]

处理 PyGame 事件。

特别是，此函数用于跟踪当前按下的按钮，并在关闭 PyGame 窗口时退出 play() 函数。

参数:

event – 要处理的事件

环境序列化

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

通过它们的构造函数参数进行序列化和反序列化的对象。

示例

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

从渲染帧保存视频。

此函数从渲染帧列表中提取视频。

参数:

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

默认的集触发器。

此函数将在集索引 \(\{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[source]

用于将 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)

示例

此函数可用于确保 step 接口与冲突 API 的兼容性。例如，如果 env 是用旧版 API 编写的，wrapper 是用新版 API 编写的，并且最终 step 输出需要使用旧版 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]

用于将 step 返回值转换为新版 step 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]

用于将 step 返回值转换为旧版 step 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]

用于测量环境 step 运行时性能的基准测试。

示例用法

`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: 测试持续时间，以秒为单位（注意：实际时间会略微超过）。