PettingZooWrapper

torchrl.envs.PettingZooWrapper(*args, **kwargs)

PettingZoo 环境包装器。

要安装 petting zoo，请遵循此处的指南 <https://github.com/Farama-Foundation/PettingZoo#installation>__。

此类是所有 PettingZoo 环境的通用 torchrl 包装器。它可以包装 pettingzoo.AECEnv 和 pettingzoo.ParallelEnv。

让我们更详细地看看

在包装的 pettingzoo.ParallelEnv 中，所有代理将在每个环境步骤中进行步进。如果任务中的代理数量不同，请将 use_mask=True。 "mask" 将作为每个组的输出提供，并用于掩盖已死亡的代理。环境将在一个代理完成时重置（除非 done_on_any 为 False）。

在包装的 pettingzoo.AECEnv 中，在每一步只有一个代理会进行操作。因此，对于此类环境，必须将 use_mask=True。 "mask" 将作为每个组的输出提供，并用于掩盖未进行操作的代理。环境仅在所有代理都完成后重置（除非 done_on_any 为 True）。

如果代理有任何不可用的操作，环境还将自动更新其 action_spec 的掩码，并为每个组输出一个 "action_mask" 来反映最新的可用操作。这应该在训练期间传递给掩码分布。

作为 torchrl 多代理的一个特性，您可以控制环境中代理的分组。您可以将代理分组（堆叠它们的张量）以在通过同一神经网络时利用向量化。您可以将代理分成不同的组，在那里它们是异构的或应该由不同的神经网络处理。要进行分组，您只需在环境构造时传递一个 group_map。

默认情况下，pettingzoo 中的代理将按名称分组。例如，对于代理 ["agent_0","agent_1","agent_2","adversary_0"]，tensordicts 将看起来像

>>> print(env.rand_action(env.reset()))
TensorDict(
    fields={
        agent: TensorDict(
            fields={
                action: Tensor(shape=torch.Size([3, 9]), device=cpu, dtype=torch.int64, is_shared=False),
                action_mask: Tensor(shape=torch.Size([3, 9]), device=cpu, dtype=torch.bool, is_shared=False),
                done: Tensor(shape=torch.Size([3, 1]), device=cpu, dtype=torch.bool, is_shared=False),
                observation: Tensor(shape=torch.Size([3, 3, 3, 2]), device=cpu, dtype=torch.int8, is_shared=False),
                terminated: Tensor(shape=torch.Size([3, 1]), device=cpu, dtype=torch.bool, is_shared=False),
                truncated: Tensor(shape=torch.Size([3, 1]), device=cpu, dtype=torch.bool, is_shared=False)},
            batch_size=torch.Size([3]))},
        adversary: TensorDict(
            fields={
                action: Tensor(shape=torch.Size([1, 9]), device=cpu, dtype=torch.int64, is_shared=False),
                action_mask: Tensor(shape=torch.Size([1, 9]), device=cpu, dtype=torch.bool, is_shared=False),
                done: Tensor(shape=torch.Size([1, 1]), device=cpu, dtype=torch.bool, is_shared=False),
                observation: Tensor(shape=torch.Size([1, 3, 3, 2]), device=cpu, dtype=torch.int8, is_shared=False),
                terminated: Tensor(shape=torch.Size([1, 1]), device=cpu, dtype=torch.bool, is_shared=False),
                truncated: Tensor(shape=torch.Size([1, 1]), device=cpu, dtype=torch.bool, is_shared=False)},
            batch_size=torch.Size([1]))},
    batch_size=torch.Size([]))
>>> print(env.group_map)
{"agent": ["agent_0", "agent_1", "agent_2"], "adversary": ["adversary_0"]}

否则，可以指定 group_map 或从一些预制选项中选择。有关更多信息，请参阅 torchrl.envs.utils.MarlGroupMapType。例如，您可以提供 MarlGroupMapType.ONE_GROUP_PER_AGENT，表明每个代理都应该拥有自己的 tensordict（类似于 pettingzoo 并行 API）。

分组对于利用数据通过同一神经网络的代理之间的向量化很有用。

参数:

• env (pettingzoo.utils.env.ParallelEnv 或 pettingzoo.utils.env.AECEnv) – 要包装的 pettingzoo 环境。

• return_state (bool, optional) – 是否从 pettingzoo 返回全局状态（并非所有环境都可用）。默认为 False。

• group_map (MarlGroupMapType 或 Dict[str, List[str]]], optional) – 如何在 tensordicts 中分组代理以用于输入/输出。默认情况下，代理将按其名称分组。否则，可以指定 group_map 或从一些预制选项中选择。有关更多信息，请参阅 torchrl.envs.utils.MarlGroupMapType。

• use_mask (bool, optional) – 环境是否应输出 "mask"。这对于包装的 pettingzoo.AECEnv 来掩盖未进行操作的代理是强制性的，并且当代理数量可变时，也应将其用于 pettingzoo.ParallelEnv。默认为 False。

• categorical_actions (bool, optional) – 如果环境操作是离散的，是否将其转换为分类或独热编码。

• seed (int, optional) – 种子。默认为 None。

• done_on_any (bool, optional) – 环境的 done 键是否通过聚合代理键（当 True 时使用 any()）或（当 False 时使用 all()）来设置。默认值（None）是对并行环境使用 any()，对 AEC 环境使用 all()。

示例

>>> # Parallel env
>>> from torchrl.envs.libs.pettingzoo import PettingZooWrapper
>>> from pettingzoo.butterfly import pistonball_v6
>>> kwargs = {"n_pistons": 21, "continuous": True}
>>> env = PettingZooWrapper(
...     env=pistonball_v6.parallel_env(**kwargs),
...     return_state=True,
...     group_map=None, # Use default for parallel (all pistons grouped together)
... )
>>> print(env.group_map)
... {'piston': ['piston_0', 'piston_1', ..., 'piston_20']}
>>> env.rollout(10)
>>> # AEC env
>>> from pettingzoo.classic import tictactoe_v3
>>> from torchrl.envs.libs.pettingzoo import PettingZooWrapper
>>> from torchrl.envs.utils import MarlGroupMapType
>>> env = PettingZooWrapper(
...     env=tictactoe_v3.env(),
...     use_mask=True, # Must use it since one player plays at a time
...     group_map=None # # Use default for AEC (one group per player)
... )
>>> print(env.group_map)
... {'player_1': ['player_1'], 'player_2': ['player_2']}
>>> env.rollout(10)