PettingZoo Wrappers#

Conversion wrappers#

AEC to Parallel#

An environment can be converted from an AEC environment to a parallel environment with the to_parallel wrapper shown below. Note that this wrapper makes the following assumptions about the underlying environment:

  1. The environment steps in a cycle, i.e. it steps through every live agent in order.

  2. The environment does not update the observations of the agents except at the end of a cycle.

Most parallel environments in PettingZoo only allocate rewards at the end of a cycle. In these environments, the reward scheme of the AEC API an the parallel API is equivalent. If an AEC environment does allocate rewards within a cycle, then the rewards will be allocated at different timesteps in the AEC environment an the Parallel environment. In particular, the AEC environment will allocate all rewards from one time the agent steps to the next time, while the Parallel environment will allocate all rewards from when the first agent stepped to the last agent stepped.

from pettingzoo.utils import to_parallel
from pettingzoo.butterfly import pistonball_v6
env = pistonball_v6.env()
env = to_parallel(env)

Parallel to AEC#

Any parallel environment can be efficiently converted to an AEC environment with the from_parallel wrapper.

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

Utility Wrappers#

We wanted our pettingzoo environments to be both easy to use and easy to implement. To combine these, we have a set of simple wrappers which provide input validation and other convenient reusable logic.

class pettingzoo.utils.wrappers.BaseWrapper(env)#

Creates a wrapper around env parameter.

All AECEnv wrappers should inherit from this base class

class pettingzoo.utils.wrappers.TerminateIllegalWrapper(env, illegal_reward)#

This wrapper terminates the game with the current player losing in case of illegal values.


illegal_reward – number that is the value of the player making an illegal move.

class pettingzoo.utils.wrappers.CaptureStdoutWrapper(env)#

Takes an environment which prints to terminal, and gives it an ansi render mode where it captures the terminal output and returns it as a string instead.

class pettingzoo.utils.wrappers.AssertOutOfBoundsWrapper(env)#

Asserts if the action given to step is outside of the action space. Applied in PettingZoo environments with discrete action spaces.

class pettingzoo.utils.wrappers.ClipOutOfBoundsWrapper(env)#

Clips the input action to fit in the continuous action space (emitting a warning if it does so).

Applied to continuous environments in pettingzoo.

class pettingzoo.utils.wrappers.OrderEnforcingWrapper(env)#

Checks if function calls or attribute access are in a disallowed order.

  • error on getting rewards, terminations, truncations, infos, agent_selection before reset

  • error on calling step, observe before reset

  • error on iterating without stepping or resetting environment.

  • warn on calling close before render or reset

  • warn on calling step after environment is terminated or truncated

You can apply these wrappers to your environment in a similar manner to the below example:

from pettingzoo.utils import OrderEnforcingWrapper
from pettingzoo.butterfly import pistonball_v6
env = pistonball_v6.env()
env = OrderEnforcingWrapper(env)