实用函数¶

播种¶

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

返回一个NumPy随机数生成器（RNG）以及从输入的种子中获取的种子值。

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

此函数在 :meth:reset 中被调用，以重置环境的初始随机数生成器。

参数:: seed – 用于创建生成器的种子
返回:: 基于NumPy的随机数生成器和生成器种子
抛出:: Error – 种子必须是一个非负整数

环境检查¶

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 检查 :attr:observation_space 和 :attr:action_space 是否正确。此外，该函数将使用各种值调用 :meth:reset、:meth:step 和 :meth:render 函数。

我们强烈建议用户在构建环境后并在项目的持续集成中调用此函数，以保持环境与Gymnasium API的更新。

参数:

env – 将要检查的 Gym 环境
warn – 忽略，之前被静音的特定警告
skip_render_check – 是否跳过渲染方法的检查。默认为False（对CI有用）
skip_close_check – 是否跳过对 close 方法的检查。默认为 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字典可能如下所示：
seed – 在重置环境时使用的随机种子。如果为 None，则不使用种子。
noop – 当没有输入按键，或输入的按键组合未知时所采取的动作。
wait_on_player – 游戏应等待用户操作

示例

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

上述代码在环境被包装的情况下也能工作，因此在验证帧级预处理不会使游戏无法进行时特别有用。

如果你想在玩游戏时绘制实时统计数据，可以使用 :class: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])[源代码]¶

在使用 :func:play 时，提供了一个回调函数来创建任意指标的实时图表。

此类通过一个函数实例化，该函数接受关于单个环境转换的信息：

obs_t: 执行动作前的观察
obs_tp1: 执行动作后的观察
action: 执行的操作
rew: 收到的奖励
terminated: 环境是否已终止
truncated: 环境是否被截断
信息: 调试信息

它应该返回从这些数据计算出的指标列表。例如，该函数可能看起来像这样::

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

:class:PlayPlot 提供了 :meth:callback 方法，该方法将传递其参数给该函数，并使用返回的值来更新指标的实时图表。

通常，这个 :meth:回调 会与 :func:播放 一起使用，以查看在播放过程中指标是如何演变的::

>>> 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 窗口时退出 :func: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[源代码]¶

默认的剧集触发器。

此函数将在剧集索引 :math:\{0, 1, 4, 8, 27, ..., k^3, ..., 729, 1000, 2000, 3000, ...\} 处触发录制

参数:: episode_id – 剧集编号
返回:: 如果应用视频计划编号

旧到新步骤API兼容性¶

函数将步骤返回值转换为 output_truncation_bool 指定的 API。

Done (旧) 步骤 API 指的是 :meth:step 方法返回 (observation, reward, done, info)。Terminated Truncated (新) 步骤 API 指的是 :meth:step 方法返回 (observation, reward, terminated, truncated, info)。（有关 API 更改的详细信息，请参阅文档）

参数:

step_returns (tuple) – 由 :meth: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的步骤接口中的兼容性。例如，如果env使用旧API编写，wrapper使用新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)

函数将步骤返回值转换为新的步骤API，无论输入API如何。

参数:

step_returns (tuple) – 由 :meth:step 返回的项目。可以是 (obs, rew, done, info) 或 (obs, rew, terminated, truncated, info)
is_vector_env (bool) – step_returns 是否来自向量环境

函数将步骤返回转换为旧步骤API，无论输入API如何。

参数:

step_returns (tuple) – 由 :meth: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: 基准测试的持续时间（秒）（注意：会稍微超出这个时间）。