【gymnasium】Env

gymnasium.Env

用于实现强化学习智能体环境的主要Gymnasium类。

通过step()和reset()函数，这个类封装了一个具有任意幕后动态的环境。环境能被一个智能体部分或者全部观察。对于多智能体环境，请看PettingZoo。

这个类的使用者需要知道的主要API方法是：

• step() 根据动作更新环境，返回下一个智能体观察，采取该动作的奖励，以及因为最近的动作终止的环境和来自环境的信息，例如度量值、调试信息。
• reset() 将环境重置为调用步骤之前所需的初始状态。返回针对一个episode的观察和信息，例如，metrics，调试信息。
• render()渲染环境以帮助可视化代理所看到的内容，示例模式为“human”、“rgb_array”、“ansi”（文本）。
• close() 关闭环境，在使用外部软件时很重要，即用于渲染的 pygame、数据库。

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

• action_space - 与有效操作对应的 Space 对象，所有有效操作都应包含在该空间内。
• observation_space - 与有效观测值相对应的 Space 对象，所有有效观测值都应包含在该空间内。
• reward_range - 对应于代理在一个情节中的最小和最大可能奖励的元组。默认奖励范围设置为$(-\infty ，+\infty )$
• spec - 环境规范，包含用于从gymnasium.make()初始化环境的信息
• metadata - 环境的元数据，即渲染模式、渲染帧率
• np_random - 环境的随机数生成器。这是在 super().reset(seed=seed) 期间和评估 self.np_random 时自动分配的。

注意：
要修改或扩展环境，请使用gymnasium.Wrapper 类
为了获得可重复的动作采样，可以使用 env.action_space.seed(123) 设置种子。

Methods

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

使用代理操作运行环境动态的一个时间步。
当一个episode结束时（终止或截断），有必要调用reset()来重置下一个episode的环境状态。
PARAMETERS:
action(ActType) – 代理提供的用于更新环境状态的操作。
RETURNS:

• observation (ObsType) - 由于代理动作，环境观察空间的一个元素作为下一个观察。一个示例是numpy 数组包含 CartPole 中杆的位置和速度。
• reward (SupportsFloat) - 采取行动的结果的奖励。
• terminated (bool) - 代理是否达到最终状态（根据任务的 MDP 定义），可以是正数或负数。一个例子是达到目标状态或从萨顿和巴顿、网格世界进入熔岩。如果为真，则用户需要调用reset()。
• truncated (bool) - 是否满足MDP范围外的截断条件。通常，这是一个时间限制，但也可用于指示代理实际越界。可用于在达到最终状态之前提前结束情节。如果为true，用户需要调用reset()
• info (dict) - 包含辅助诊断信息（有助于调试、学习和记录）。例如，这可能包含：描述代理绩效状态的指标、观察隐藏的变量或组合起来产生总奖励的单个奖励​​项。在 OpenAI Gym <v26 中，它包含“TimeLimit.truncated”来区分截断和终止，但是，这已被弃用，有利于返回终止和截断的变量。
• done (bool) - （已弃用）表示剧集是否已结束的布尔值，在这种情况下，进一步的 step() 调用将返回未定义的结果。这在 OpenAI Gym v26 中被删除，以支持终止和截断属性。发出完成信号的原因可能有多种：可能环境下的任务已成功解决，超出了特定的时间限制，或者物理模拟已进入无效状态。

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

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

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

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

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

• seed (optional int) - 用于初始化环境的 PRNG (np_random) 的种子。如果环境还没有 PRNG 并且传递了 seed=None （默认选项），则将从某些熵源（例如时间戳或 /dev/urandom）中选择种子。但是，如果环境已经有PRNG并且传递了seed=None，则PRNG将不会被重置。如果传递一个整数，即使 PRNG 已经存在，它也会被重置。通常，您希望在环境初始化后立即传递一个整数，然后不再传递。
• options (optional dict) - 用于指定如何重置环境的附加信息（可选，取决于具体环境）。
  RETURNS:
• observation (ObsType) – 初始状态的观察。这将是 Observation_space 的一个元素（通常是 numpy 数组），类似于 step() 返回的观察结果。
• info（字典）——该字典包含补充观察的辅助信息。它应该类似于step()返回的信息。

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

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

环境的元数据渲染模式（env.metadata[“render_modes”]）应包含实现渲染模式的可能方法。此外，大多数渲染模式的列表版本是通过gymnasium.make 实现的，它会自动应用包装器来收集渲染帧。

按照惯例，如果 render_mode 是：

• None（默认）：不计算渲染。
• “human”：环境在当前显示器或终端中持续渲染，通常供人使用。这种渲染应该在step()期间发生，并且不需要调用render()。返回无。
• “rgb_array”：返回表示环境当前状态的单个帧。帧是一个 np.ndarray，形状为 (x, y, 3)，表示 x×y 像素图像的 RGB 值。
• “ansi”：返回一个字符串 (str) 或 StringIO.StringIO，其中包含每个时间步的终端样式文本表示形式。文本可以包含换行符和 ANSI 转义序列（例如颜色）。
• “rgb_array_list”和“ansi_list”：通过包装器可以实现基于列表的渲染模式版本（人类除外），在gymnasium.make(…, render_mode=“rgb_array_list”)期间自动应用的gymnasium.wrappers.RenderCollection。调用 render() 或 Reset() 后，收集的帧将弹出。

Changed in version 0.25.0: The render function was changed to no longer accept parameters, rather these parameters should be specified in the environment initialised, i.e., gymnasium.make(“CartPole-v1”, render_mode=“human”)

Attributes

Env.action_space: spaces.Space[ActType]

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

env.action_space
Discrete(2)
env.observation_space
Box(-3.4028234663852886e+38, 3.4028234663852886e+38, (4,), float32)

Env.observation_space: spaces.Space[ObsType]

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

env.observation_space.high
array([4.8000002e+00, 3.4028235e+38, 4.1887903e-01, 3.4028235e+38], dtype=float32)
env.observation_space.low
array([-4.8000002e+00, -3.4028235e+38, -4.1887903e-01, -3.4028235e+38], dtype=float32)

Env.metadata: dict[str, Any] = {‘render_modes’: []}

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

Env.render_mode: str | None = None

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

Env.reward_range = (-inf, inf)

Env.spec: EnvSpec | None = None

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

Additional Methods

gymnasium.Env.close(self)

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

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

property Env.unwrapped: Env[ObsType, ActType]

返回基本的非包装环境

property Env.np_random: Generator

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

例子

import gymnasium as gym
env = gym.make("LunarLander-v2", render_mode="human")
observation, info = env.reset()

for _ in range(1000):
    action = env.action_space.sample()  # agent policy that uses the observation and info
    observation, reward, terminated, truncated, info = env.step(action)

    if terminated or truncated:
        observation, info = env.reset()

env.close()