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()