PettingZoo 封装器¶

PettingZoo 包括以下几种类型的封装器

转换封装器：用于在 AEC 和 Parallel API 之间转换环境的封装器
实用封装器：提供方便可重用逻辑的一组封装器，例如强制执行回合顺序或裁剪超出范围的动作。

转换封装器¶

AEC 转 Parallel¶

pettingzoo.utils.conversions.aec_to_parallel(aec_env: AECEnv[AgentID, ObsType, ActionType]) → ParallelEnv[AgentID, ObsType, ActionType][source]¶

将 AEC 环境转换为 Parallel 环境。

对于使用 parallel_to_aec_wrapper 封装的现有 Parallel 环境，此函数将返回原始的 Parallel 环境。否则，它将应用 aec_to_parallel_wrapper 来转换环境。

环境可以使用如下所示的 aec_to_parallel 封装器从 AEC 环境转换为 Parallel 环境。请注意，此封装器对底层环境做出了以下假设

环境按回合步进，即它按顺序遍历每个活跃的智能体。
环境只在回合结束时更新智能体的观测。

PettingZoo 中的大多数 Parallel 环境只在回合结束时分配奖励。在这些环境中，AEC API 和 Parallel API 的奖励机制是等效的。如果 AEC 环境在一个回合内分配奖励，那么奖励将在 AEC 环境和 Parallel 环境中分配到不同的时间步。特别是，AEC 环境将分配智能体从一个步进到下一个步进之间的所有奖励，而 Parallel 环境将分配从第一个智能体步进到最后一个智能体步进之间的所有奖励。

将 AEC 环境转换为 Parallel 环境

from pettingzoo.utils.conversions import aec_to_parallel
from pettingzoo.butterfly import pistonball_v6
env = pistonball_v6.env()
env = aec_to_parallel(env)

Parallel 转 AEC¶

pettingzoo.utils.conversions.parallel_to_aec(par_env: ParallelEnv[AgentID, ObsType, ActionType | None]) → AECEnv[AgentID, ObsType, ActionType | None][source]¶

将 Parallel 环境转换为 AEC 环境。

对于使用 aec_to_parallel_wrapper 封装的现有 AEC 环境，此函数将返回原始的 AEC 环境。否则，它将应用 parallel_to_aec_wrapper 来转换环境。

任何 Parallel 环境都可以使用 parallel_to_aec 封装器高效地转换为 AEC 环境。

将 Parallel 环境转换为 AEC 环境

from pettingzoo.utils import parallel_to_aec
from pettingzoo.butterfly import pistonball_v6
env = pistonball_v6.parallel_env()
env = parallel_to_aec(env)

实用封装器¶

我们希望 PettingZoo 环境既易于使用又易于实现。为了结合这两点，我们提供了一组简单的封装器，它们提供输入验证和其他方便的可重用逻辑。

您可以按照以下示例类似地将这些封装器应用于您的环境

封装 AEC 环境

from pettingzoo.utils import TerminateIllegalWrapper
from pettingzoo.classic import tictactoe_v3
env = tictactoe_v3.env()
env = TerminateIllegalWrapper(env, illegal_reward=-1)

env.reset()
for agent in env.agent_iter():
    observation, reward, termination, truncation, info = env.last()
    if termination or truncation:
        action = None
    else:
        action = env.action_space(agent).sample()  # this is where you would insert your policy
    env.step(action)
env.close()

注意：大多数 AEC 环境在其初始化中包含 TerminateIllegalWrapper，因此此代码不会改变环境的行为。

封装 Parallel 环境。

from pettingzoo.utils import BaseParallelWrapper
from pettingzoo.butterfly import pistonball_v6

parallel_env = pistonball_v6.parallel_env(render_mode="human")
parallel_env = BaseParallelWrapper(parallel_env)

observations, infos = parallel_env.reset()

while parallel_env.agents:
    actions = {agent: parallel_env.action_space(agent).sample() for agent in parallel_env.agents}  # this is where you would insert your policy
    observations, rewards, terminations, truncations, infos = parallel_env.step(actions)

警告

PettingZoo 中包含的封装器目前不支持 Parallel 环境，要使用它们，您必须将环境转换为 AEC，应用封装器，然后再转换回 Parallel。

from pettingzoo.utils import ClipOutOfBoundsWrapper
from pettingzoo.sisl import multiwalker_v9
from pettingzoo.utils import aec_to_parallel

parallel_env = multiwalker_v9.env(render_mode="human")
parallel_env = ClipOutOfBoundsWrapper(parallel_env)
parallel_env = aec_to_parallel(parallel_env)

observations, infos = parallel_env.reset()

while parallel_env.agents:
    actions = {agent: parallel_env.action_space(agent).sample() for agent in parallel_env.agents}  # this is where you would insert your policy
    observations, rewards, terminations, truncations, infos = parallel_env.step(actions)

class pettingzoo.utils.wrappers.BaseWrapper(env: AECEnv[AgentID, ObsType, ActionType])[source]¶

在 env 参数周围创建一个封装器。

所有 AECEnv 封装器都应该继承自此基类

class pettingzoo.utils.wrappers.TerminateIllegalWrapper(env: AECEnv[AgentID, ObsType, ActionType], illegal_reward: float)[source]¶

此封装器在出现非法值时终止游戏，当前玩家判负。

参数:: illegal_reward – 玩家做出非法动作时的惩罚值。

class pettingzoo.utils.wrappers.CaptureStdoutWrapper(env: AECEnv)[source]¶: 接收一个向终端打印的环境，并为其提供一个 ansi 渲染模式，在该模式下，它捕获终端输出并将其作为字符串返回。

class pettingzoo.utils.wrappers.AssertOutOfBoundsWrapper(env: AECEnv[AgentID, ObsType, ActionType])[source]¶: 断言提供给 step 的动作是否超出动作空间。

class pettingzoo.utils.wrappers.ClipOutOfBoundsWrapper(env: AECEnv)[source]¶

裁剪输入动作以适应连续动作空间（如果裁剪则发出警告）。

应用于 pettingzoo 中的连续环境。

class pettingzoo.utils.wrappers.OrderEnforcingWrapper(env: AECEnv[AgentID, ObsType, ActionType])[source]¶

检查函数调用或属性访问是否处于不允许的顺序。

将引发以下错误：* AttributeError 如果在 reset() 之前访问了以下任何内容

rewards, terminations, truncations, infos, agent_selection, num_agents, agents。

如果在 reset 之前调用了以下任何内容，则会出错：render(), step(), observe(), state(), agent_iter()
如果在没有剩余智能体时调用 step()，则会发出警告。