Env

class gymnasium.Env[source]

实现强化学习 Agent 环境的主要 Gymnasium 类。

此类通过 step() 和 reset() 函数封装了一个具有任意幕后动态的环境。环境可以被单个 agent 部分或完全观察到。对于多 agent 环境，请参阅 PettingZoo。

用户需要了解的主要 API 方法是

  • step() - 使用动作更新环境，返回下一个 agent 观测、执行该动作的奖励、环境是否由于最新动作而终止或截断，以及来自环境的关于步骤的信息，即指标、调试信息。

  • reset() - 将环境重置为初始状态，在调用 step 之前是必需的。返回 episode 的第一个 agent 观测和信息，即指标、调试信息。

  • render() - 渲染环境以帮助可视化 agent 所见，示例模式为 “human”、“rgb_array”、“ansi”（文本）。

  • close() - 关闭环境，当使用外部软件时（例如，pygame 用于渲染，数据库）非常重要

环境具有额外的属性供用户理解实现

  • action_space - 与有效动作对应的 Space 对象，所有有效动作都应包含在该空间内。

  • observation_space - 与有效观测对应的 Space 对象，所有有效观测都应包含在该空间内。

  • spec - 环境 spec，其中包含用于从 gymnasium.make() 初始化环境的信息

  • metadata - 环境的元数据，例如 {“render_modes”: [“rgb_array”, “human”], “render_fps”: 30}。对于 Jax 或 Torch，可以使用 “jax”=True 或 “torch”=True 向用户指示。

  • np_random - 环境的随机数生成器。这在 super().reset(seed=seed) 期间以及评估 np_random 时自动分配。

另请参阅

对于修改或扩展环境，请使用 gymnasium.Wrapper 类

注意

为了获得可重复的动作采样，可以使用 env.action_space.seed(123) 设置种子。

注意

对于严格的类型检查（例如 mypy 或 pyright），Env 是一个具有两个参数化类型的泛型类：ObsType 和 ActType。ObsType 和 ActType 是 reset() 和 step() 中使用的观测和动作的预期类型。环境的 observation_space 和 action_space 应具有类型 Space[ObsType] 和 Space[ActType]，请参阅 space 的实现以查找其参数化类型。

方法

Env.step(action: ActType) → tuple[ObsType, SupportsFloat, bool, bool, dict[str, Any]][source]

使用 agent 动作运行环境动态的一个时间步。

当 episode 结束时（terminated or truncated），有必要调用 reset() 以重置此环境的状态以进行下一个 episode。

Changed in version 0.26: Step API 已更改，删除了 done，而使用 terminated 和 truncated，以便更清楚地向用户说明环境何时终止或截断，这对于强化学习自举算法至关重要。

参数:

action (ActType) – agent 提供的用于更新环境状态的动作。

返回:

  • observation (ObsType) – 环境的 observation_space 的一个元素，作为由于 agent 动作而产生的下一个观测。例如，一个 numpy 数组，其中包含 CartPole 中杆的位置和速度。

  • reward (SupportsFloat) – 执行动作的奖励。

  • terminated (bool) – agent 是否达到终端状态（根据任务的 MDP 定义），这可以是正面的或负面的。例如，达到目标状态或从 Sutton 和 Barto Gridworld 进入熔岩。如果为 true，则用户需要调用 reset()。

  • truncated (bool) – 是否满足 MDP 范围之外的截断条件。通常，这是一个时间限制，但也可能用于指示 agent 物理上超出边界。可用于在达到终端状态之前过早结束 episode。如果为 true，则用户需要调用 reset()。

  • info (dict) – 包含辅助诊断信息（有助于调试、学习和日志记录）。例如，这可能包含：描述 agent 性能状态的指标、观测中隐藏的变量或组合以产生总奖励的各个奖励项。在 OpenAI Gym <v26 中，它包含 “TimeLimit.truncated” 以区分截断和终止，但这在返回 terminated 和 truncated 变量时已被弃用。

  • done (bool) – （已弃用）一个布尔值，指示 episode 是否已结束，在这种情况下，进一步的 step() 调用将返回未定义的结果。这在 OpenAI Gym v26 中被删除，取而代之的是 terminated 和 truncated 属性。可能会因不同原因发出 done 信号：可能是成功解决了环境的基础任务，超过了某个时间限制，或者物理模拟已进入无效状态。

Env.reset(*, seed: int | None = None, options: dict[str, Any] | None = None) → tuple[ObsType, dict[str, Any]][source]

将环境重置为初始内部状态，返回初始观测和信息。

此方法生成一个新的起始状态，通常带有一些随机性，以确保 agent 探索状态空间并学习关于环境的通用策略。这种随机性可以通过 seed 参数控制，否则如果环境已经有一个随机数生成器，并且使用 seed=None 调用 reset()，则 RNG 不会被重置。

因此，reset() 应该（在典型用例中）在初始化后立即使用种子调用，然后不再调用。

对于自定义环境，reset() 的第一行应该是 super().reset(seed=seed)，它正确地实现了播种。

Changed in version v0.25: return_info 参数已删除，现在期望返回 info。

参数:

  • seed (optional int) – 用于初始化环境的 PRNG (np_random) 和只读属性 np_random_seed 的种子。如果环境尚不具有 PRNG 且传递了 seed=None（默认选项），则将从某个熵源（例如，时间戳或 /dev/urandom）中选择种子。但是，如果环境已经具有 PRNG 且传递了 seed=None，则 PRNG 将不会被重置，并且环境的 np_random_seed 将不会被更改。如果传递整数，即使 PRNG 已经存在，也会被重置。通常，您希望在环境初始化后立即传递整数，然后不再传递。请参考上面的最小示例，以查看此范例的实际应用。

  • options (optional dict) – 用于指定如何重置环境的附加信息（可选，取决于具体环境）

返回:

  • observation (ObsType) – 初始状态的观测。这将是 observation_space 的一个元素（通常是 numpy 数组），并且类似于 step() 返回的观测。

  • info (dictionary) – 此字典包含补充 observation 的辅助信息。它应类似于 step() 返回的 info。

Env.render() → RenderFrame | list[RenderFrame] | None[source]

计算在环境初始化期间由 render_mode 指定的渲染帧。

环境的 metadata 渲染模式 (env.metadata[“render_modes”]) 应包含实现渲染模式的可能方式。此外，大多数渲染模式的列表版本通过 gymnasium.make 实现，后者自动应用 wrapper 来收集渲染帧。

注意

由于 render_mode 在 __init__ 期间已知，因此用于渲染环境状态的对象应在 __init__ 中初始化。

按照惯例，如果 render_mode 是

  • None（默认）：不计算渲染。

  • “human”：环境在当前显示器或终端中持续渲染，通常供人消费。此渲染应在 step() 期间发生，并且不需要调用 render()。返回 None。

  • “rgb_array”：返回表示环境当前状态的单个帧。帧是形状为 (x, y, 3) 的 np.ndarray，表示 x 乘 y 像素图像的 RGB 值。

  • “ansi”：返回字符串 (str) 或 StringIO.StringIO，其中包含每个时间步的终端样式文本表示形式。文本可以包括换行符和 ANSI 转义序列（例如，用于颜色）。

  • “rgb_array_list” 和 “ansi_list”：列表版本的渲染模式可以通过 wrapper gymnasium.wrappers.RenderCollection 实现（human 除外），该 wrapper 在 gymnasium.make(..., render_mode="rgb_array_list") 期间自动应用。收集的帧在调用 render() 或 reset() 后弹出。

注意

确保您的类的 metadata "render_modes" 键包含支持模式的列表。

Changed in version 0.25.0: render 函数已更改为不再接受参数，而是应在环境初始化中指定这些参数，即 gymnasium.make("CartPole-v1", render_mode="human")

Env.close()[source]

在用户完成使用环境后，close 包含清理环境所需的代码。

这对于关闭渲染窗口、数据库或 HTTP 连接至关重要。在已关闭的环境上调用 close 没有效果，也不会引发错误。

属性

Env.action_space: spaces.Space[ActType]

与有效动作对应的 Space 对象，所有有效动作都应包含在空间内。例如，如果动作空间的类型为 Discrete 并给出值 Discrete(2)，则表示有两个有效的离散动作：0 和 1。

>>> env.action_space
Discrete(2)
>>> env.observation_space
Box(-inf, inf, (4,), float32)
Env.observation_space: spaces.Space[ObsType]

与有效观测对应的 Space 对象，所有有效观测都应包含在空间内。例如，如果观测空间的类型为 Box 且对象的形状为 (4,)，则表示有效的观测将是 4 个数字的数组。我们还可以使用属性检查 box 边界。

>>> env.observation_space.high
array([4.8000002e+00, inf, 4.1887903e-01, inf], dtype=float32)
>>> env.observation_space.low
array([-4.8000002e+00, -inf, -4.1887903e-01, -inf], dtype=float32)
Env.metadata: dict[str, Any] = {'render_modes': []}

环境的元数据，包含渲染模式、渲染 fps 等

Env.render_mode: str | None = None

在初始化时确定的环境的渲染模式

Env.spec: EnvSpec | None = None

环境的 EnvSpec，通常在 gymnasium.make() 期间设置

property Env.unwrapped: Env[ObsType, ActType]

返回基本的未包装环境。

返回:

Env – 基本的未包装 gymnasium.Env 实例

property Env.np_random: Generator

返回环境的内部 _np_random，如果未设置，则将使用随机种子初始化。

返回:

`np.random.Generator` 的实例

property Env.np_random_seed: int

返回环境的内部 _np_random_seed，如果未设置，则将首先使用随机整数作为种子进行初始化。

如果直接设置了 np_random_seed，而不是通过 reset() 或 set_np_random_through_seed()，则种子将取值 -1。

返回:

int – 当前 np_random 的种子，如果 rng 的种子未知，则为 -1

实现环境

在实现环境时，必须创建 Env.reset() 和 Env.step() 函数来描述环境的动态。有关更多信息，请参阅环境创建教程。

创建环境

为了创建一个环境，gymnasium 提供了 make() 来初始化环境以及几个重要的包装器。此外，gymnasium 提供了 make_vec() 用于创建向量环境，并使用 pprint_registry() 查看所有可以创建的环境。