Skip to content

Environments API

Environment APIs are split into base factories/classes and temporal constraint wrappers. Constraint wrappers attach LTLf objectives through BoolRewardWrapper.

Matrix

Bases: ParallelEnv

Repeated 2-player stag hunt with global binary observations.

Observations expose the last joint action and whether the last stage was unmirrored: ch0 = player_0 chose Hare ch1 = player_0 chose Stag ch2 = player_1 chose Hare ch3 = player_1 chose Stag ch4 = last outcome was off-diagonal

Bases: SHLabelMixin, BoolRewardWrapper

Objective wrapper for a hare-then-stag handshake without mismatches.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Bases: SHLabelMixin, BoolRewardWrapper

Objective wrapper for reaching sustained stag play after coordination.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Bases: SHLabelMixin, BoolRewardWrapper

Objective wrapper requiring both hare and stag modes without mismatches.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Pursuit

Bases: ParallelEnv

Pursuit Evasion (Parallel PettingZoo) Also referred to as Guard-Gridworld.

  • Agents: 2 or 3 (0 is the Guard; 1 and 2 are normal).
  • Actions: {Left, Right, Up, Down, Stay}. Moves into walls/bounds are ignored.
  • Collision: any two agents share a cell after the simultaneous move.
  • Goal: true iff agent 0 OR 1 is in the goal region.

Rewards default to 0; optional shaping provided via constructor. Observations (globalised): binary channels shared by all agents: [Wall, Goal, A0, A1, (A2)] with dtype=np.float32. If flatten_observations is True, this is flattened to (HWC,).

state_space property

Describe the shape/dtype of state().

action_names(action)

Human-friendly name for an action integer ID.

channel_names()

Human-friendly names for each observation channel index.

Channels are

0: Wall 1: Goal 2+: Agents (0 = guard, others = normal agents)

get_state()

Tuple layout

( agents: tuple[str, ...], t: int, collision_ever: bool, goal_last_step: bool, collision_last_step: bool, agent_pos: tuple[Coord, ...] # ordered by possible_agents rng_state: object )

num_cells()

Number of spatial cells in the layered observation grid.

state()

Global, agent-agnostic state (same content as obs), matches state_space().

Bases: PELabelMixin, BoolRewardWrapper

Classic guard-vs-intruder pursuit objective wrapper.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Bases: PELabelMixin, BoolRewardWrapper

Objective wrapper for guard capture versus intruder stealth.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Bases: PELabelMixin, BoolRewardWrapper

Objective wrapper for coordinated intruder goal reaching.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Bases: PELabelMixin, BoolRewardWrapper

Objective wrapper for reaching the gridworld gap without collisions.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Chemistry

Build a native PettingZoo Chemistry substrate.

Bases: NativeRGBObservationWrapper

Chemistry-specific normalized RGB policy adapter.

Bases: ChemistryLabelMixin, BoolRewardWrapper

Objective wrapper for eventually metabolizing food per agent.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Bases: ChemistryLabelMixin, BoolRewardWrapper

Objective wrapper requiring each agent's food event before shared XY.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Bases: ChemistryLabelMixin, BoolRewardWrapper

Objective wrapper requiring each agent's food event before its XY event.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Bases: ChemistryLabelMixin, BoolRewardWrapper

Objective wrapper for eventually metabolizing XY per agent.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Harvest

Build a native PettingZoo Commons Harvest substrate.

Bases: NativeRGBObservationWrapper

Harvest-specific normalized RGB policy adapter.

Bases: HarvestLabelMixin, BoolRewardWrapper

Objective wrapper for eventually collecting an apple per agent.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Bases: HarvestLabelMixin, BoolRewardWrapper

Objective wrapper for collecting an apple without punishment per agent.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Territory

Build a native PettingZoo Territory substrate.

Bases: NativeRGBObservationWrapper

Territory-specific RGB adapter preserving side-channel infos for labels.

Bases: TerritoryLabelMixin, BoolRewardWrapper

Objective wrapper for eventually claiming a resource per agent.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Bases: TerritoryLabelMixin, BoolRewardWrapper

Objective wrapper for resource claims while all zappers stay ready.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Bases: TerritoryLabelMixin, BoolRewardWrapper

Two-agent role objective where player 0 claims and player 1 avoids claims.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Gift Refinements

Build the native PettingZoo Gift Refinements substrate.

Bases: NativeRGBObservationWrapper

Gift Refinements RGB adapter preserving inventory and reward infos.

Bases: GiftRefinementsLabelMixin, BoolRewardWrapper

Objective wrapper for eventually consuming tokens per agent.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.

Bases: GiftRefinementsLabelMixin, BoolRewardWrapper

Objective wrapper for receiving a refined gift before consuming tokens.

export(to_file=True, dir='exports', filename='bool_rm.dot')

Export one automaton per agent monitor.

  • If filename contains "{agent}", it will be formatted with the agent id. Example: filename="rm_{agent}.dot"
  • Otherwise, we append the agent id before the extension: "bool_rm.dot" -> "bool_rm_player_0.dot"
  • If filename includes subdirectories (e.g. "graphs/rm.dot"), they are created too.