工具

PettingZoo 提供了一系列帮助实用工具，为与环境交互提供了额外的功能。

注意：另请参见 PettingZoo 包装器，它提供了用于自定义环境的额外功能。

平均总奖励

pettingzoo.utils.average_total_reward.average_total_reward(env: AECEnv, max_episodes: int = 100, max_steps: int = 10000000000) → float

计算 AEC 环境在多个回合中的平均总奖励。

使用随机动作运行环境对象，直到达到最大回合数或最大步数。奖励在所有智能体之间累加，因此不适用于零和博弈。

如文档中所示，环境的平均总奖励是在回合中所有步的所有智能体的奖励总和，再在所有回合中取平均。

这个值对于建立最简单的基准：随机策略，非常重要。

from pettingzoo.utils import average_total_reward
from pettingzoo.butterfly import pistonball_v6
env = pistonball_v6.env()
average_total_reward(env, max_episodes=100, max_steps=10000000000)

其中 max_episodes 和 max_steps 都限制了总评估次数（当其中一个达到时评估停止）

观测值保存

pettingzoo.utils.save_observation.save_observation(env: AECEnv[AgentID, Any, Any], agent: AgentID | None = None, all_agents: bool = False, save_dir: str = os.getcwd()) → None

如果游戏中的智能体生成图像观测值，则可以将观测值保存到图像文件中。此函数接受环境和指定的智能体。如果没有指定 agent，则选择当前环境中的选中智能体。如果 all_agents 传入为 True，则保存环境中所有智能体的观测值。默认情况下，图像保存到当前工作目录中与环境同名的文件夹中。保存的图像将与观测智能体的名称匹配。如果传入 save_dir，则会创建一个新文件夹用于保存图像。此函数可以在训练/评估期间根据需要调用，这就是为什么环境在使用前必须重置的原因。

from pettingzoo.utils import save_observation
from pettingzoo.butterfly import pistonball_v6
env = pistonball_v6.env()
env.reset(seed=42)
save_observation(env, agent=None, all_agents=False)

捕获标准输出

被 CaptureStdoutWrapper 使用的基类。将系统标准输出捕获为变量中的字符串值。

class pettingzoo.utils.capture_stdout.capture_stdout

允许捕获标准输出的类。

示例

>>> from pettingzoo.utils.capture_stdout import capture_stdout
>>> with capture_stdout() as var:
...     print("test")
...     data = var.getvalue()
...
>>> data
'test\n'

智能体选择器

智能体选择器工具允许在 AEC 环境中轻松循环智能体。它可以在任何时候重置或使用新的顺序重新初始化，从而允许更改回合顺序或处理动态数量的智能体（有关生成/杀死智能体的示例，请参见 骑士弓箭手僵尸）。

注意：虽然许多 PettingZoo 环境在内部使用 AgentSelector 来管理智能体循环，但在与环境交互时，它不适合外部使用。请改用 for agent in env.agent_iter()（参见 AEC API 用法）。

class pettingzoo.utils.agent_selector.AgentSelector(agent_order: list[Any])

每次调用 agent_select 时，按给定顺序输出一个智能体。

可以重新初始化为新顺序。

示例

>>> from pettingzoo.utils import AgentSelector
>>> agent_selector = AgentSelector(agent_order=["player1", "player2"])
>>> agent_selector.reset()
'player1'
>>> agent_selector.next()
'player2'
>>> agent_selector.is_last()
True
>>> agent_selector.reinit(agent_order=["player2", "player1"])
>>> agent_selector.next()
'player2'
>>> agent_selector.is_last()
False

is_first() → bool

检查当前智能体是否是循环中的第一个智能体。

is_last() → bool

检查当前智能体是否是循环中的最后一个智能体。

next() → Any

获取下一个智能体。

reinit(agent_order: list[Any]) → None

重新初始化为新顺序。

reset() → Any

重置为原始顺序。

class pettingzoo.utils.agent_selector.agent_selector(*args, **kwargs)

AgentSelector 的已弃用版本。请改用 AgentSelector。

环境日志记录器

EnvLogger 为环境提供常见警告和错误功能，并允许自定义消息。它在 PettingZoo 包装器 内部使用。

class pettingzoo.utils.env_logger.EnvLogger

用于记录环境的警告和错误。

static error_agent_iter_before_reset() → None

错误：agent_iter() 必须在调用 reset() 之后调用。。

static error_nan_action() → None

错误：step() 不能接受 NaN 动作。。

static error_observe_before_reset() → None

错误：observe 必须在调用 reset() 之后调用。。

static error_possible_agents_attribute_missing(name: str) → None

警告：[ERROR]: 此环境不支持 {attribute}.。

static error_render_before_reset() → None

错误：render 必须在调用 reset() 之后调用。。

static error_state_before_reset() → None

错误：state 必须在调用 reset() 之后调用。。

static error_step_before_reset() → None

错误：step 必须在调用 reset() 之后调用。。

static flush() → None

刷新 EnvLogger 输出。

static get_logger() → Logger

返回日志记录器对象。

mqueue: list[Any] = []

static suppress_output() → None

抑制 EnvLogger 输出。

static unsuppress_output() → None

将 EnvLogger 输出重置为可打印。

static warn_action_out_of_bound(action: Any, action_space: Space, backup_policy: str) → None

警告：[WARNING]: 收到动作 {action} 超出动作空间 {action_space}.。

static warn_on_illegal_move() → None

警告：[WARNING]: 进行了非法移动，游戏结束，当前玩家失败。。

static warn_step_after_terminated_truncated() → None

警告：[WARNING]: 在所有智能体终止或截断后调用了 step()。应先调用 reset()。