### Install SuperSuit from PyPI

Source: https://github.com/farama-foundation/supersuit/blob/main/README.md

Installs SuperSuit using pip after setting up a virtual environment. Ensure pip is upgraded before installation.

```bash
python3 -m venv env
source env/bin/activate
pip install --upgrade pip
pip install supersuit
```

--------------------------------

### Info Dictionary Example

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/06_types.md

Example demonstrating how to access the info dictionary returned from environment reset and step methods in SuperSuit. The info dictionary can contain environment-specific keys.

```python
obs, info = env.reset()
print(info)  # {'ale.lives': 5}

obs, rew, term, trunc, info = env.step(action)
print(info)  # {'ale.lives': 5, 'terminal_observation': array(...)}
```

--------------------------------

### Install SuperSuit from Source

Source: https://github.com/farama-foundation/supersuit/blob/main/README.md

Installs SuperSuit from its source code after cloning the repository. This method requires cloning the repo and navigating to its directory.

```bash
python3 -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -e .
```

--------------------------------

### Multi-Agent Setup with Supersuit Wrappers

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/README.md

Demonstrates how to apply several Supersuit wrappers to a PettingZoo environment for multi-agent reinforcement learning. This setup homogenizes observation and action spaces and adds agent indicators.

```python
from pettingzoo.butterfly import pistonball_v0
from supersuit import pad_observations_v0, pad_action_space_v0, agent_indicator_v0

env = pistonball_v0.parallel_env()
env = pad_observations_v0(env)
env = pad_action_space_v0(env)
env = agent_indicator_v0(env)
```

--------------------------------

### Complete Training Example with AEC Vector Environments

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/05_aec_vector_environments.md

A comprehensive example demonstrating environment preprocessing, vectorization, and data collection for training using AEC vector environments. This example includes observation and action space padding.

```python
import numpy as np
from pettingzoo.butterfly import pistonball_v0
from supersuit import (
    pad_observations_v0,
    pad_action_space_v0,
    vectorize_aec_env_v0
)

# Create and preprocess environment
env = pistonball_v0.env()
env = pad_observations_v0(env)
env = pad_action_space_v0(env)

# Vectorize
vec_env = vectorize_aec_env_v0(env, num_envs=4, num_cpus=0)

# Collect training data
vec_env.reset(seed=42)
episode_steps = 0
max_steps = 5000

for agent in vec_env.agent_iter(max_iter=max_steps):
    # Get observations for all environments
    obs = vec_env.observe(agent)
    
    # Sample actions
    actions = np.array([
        vec_env.action_space(agent).sample()
        for _ in range(vec_env.num_envs)
    ])
    
    # Step all environments
    vec_env.step(actions)
    
    # Get results
    obs_new, rewards, dones, env_dones, passes, infos = vec_env.last()
    
    episode_steps += 1
    
    # Your training logic here
    # process(obs, actions, rewards, obs_new, dones)
```

--------------------------------

### Basic Preprocessing with SuperSuit Wrappers

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/README.md

Applies resizing, color reduction, and frame stacking to a Gymnasium environment for observation preprocessing. Ensure Gymnasium and SuperSuit are installed.

```python
import gymnasium
from supersuit import color_reduction_v0, frame_stack_v1, resize_v1

env = gymnasium.make('SpaceInvaders-v5')
env = resize_v1(env, 84, 84)
env = color_reduction_v0(env, 'full')
env = frame_stack_v1(env, stack_size=4)

obs, info = env.reset()
```

--------------------------------

### Gymnasium Discrete Space Example

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/06_types.md

Illustrates creating a Gymnasium Discrete space, representing a finite set of options. This is compatible with wrappers like frame_stack.

```python
from gymnasium.spaces import Discrete

space = Discrete(n=4)  # Actions 0, 1, 2, 3
```

--------------------------------

### Vectorized Training with Stable-Baselines3

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/00_overview.md

This example shows how to vectorize a Gymnasium environment using Supersuit for efficient training with Stable-Baselines3. It creates a vectorized environment and trains a PPO agent.

```python
import gymnasium
from stable_baselines3 import PPO
from supersuit import stable_baselines3_vec_env_v0

env = gymnasium.make('CartPole-v1')
vec_env = stable_baselines3_vec_env_v0(env, num_envs=8, multiprocessing=True)

agent = PPO('MlpPolicy', vec_env)
agent.learn(total_timesteps=100000)
```

--------------------------------

### WrapperChooser Usage Example

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/08_utilities_and_internals.md

Demonstrates how to instantiate and use WrapperChooser with custom wrapper classes. Automatically selects the correct wrapper based on the environment.

```python
from supersuit.utils.wrapper_chooser import WrapperChooser

# Define implementations
class MyGymWrapper(gymnasium.Wrapper):
    def __init__(self, env):
        super().__init__(env)

class MyAecWrapper(BaseWrapper):
    def __init__(self, env):
        super().__init__(env)

# Create chooser
my_wrapper_v0 = WrapperChooser(
    gym_wrapper=MyGymWrapper,
    aec_wrapper=MyAecWrapper
)

# Use like a regular wrapper
env = gymnasium.make('CartPole-v1')
env = my_wrapper_v0(env)  # Automatically uses MyGymWrapper
```

--------------------------------

### Environment Type Detection and Wrapper Application

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/00_overview.md

This example illustrates how Supersuit automatically detects different environment types (Gymnasium, PettingZoo AEC, PettingZoo Parallel) and applies wrappers consistently across them. The `frame_stack_v1` wrapper is used here as an example.

```python
import gymnasium
from pettingzoo.butterfly import pistonball_v0
from supersuit import frame_stack_v1

# Gymnasium environment
gym_env = gymnasium.make('CartPole-v1')
gym_env = frame_stack_v1(gym_env, 4)

# PettingZoo AEC environment
aec_env = pistonball_v0.env()
aec_env = frame_stack_v1(aec_env, 4)

# PettingZoo Parallel environment
par_env = pistonball_v0.parallel_env()
par_env = frame_stack_v1(par_env, 4)

# Same wrapper works for all types!
```

--------------------------------

### Gymnasium Box Space Example

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/06_types.md

Demonstrates the creation of a Gymnasium Box space, suitable for continuous or discrete multi-dimensional spaces. This is often used with wrappers like color_reduction and normalize_obs.

```python
from gymnasium.spaces import Box
import numpy as np

space = Box(low=0, high=255, shape=(210, 160, 3), dtype=np.uint8)
```

--------------------------------

### Optimizing Wrapper Order for Performance

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/00_overview.md

This example illustrates the importance of wrapper order for performance. It demonstrates a 'good' order where computationally cheaper wrappers are applied before more expensive ones like frame stacking.

```python
# Good order: cheap ops first
env = resize_v1(env, 84, 84)
env = color_reduction_v0(env, 'full')
env = frame_stack_v1(env, 4)  # More expensive

# Bad order: expensive ops first
env = frame_stack_v1(env, 4)  # Stacking 210x160x3
env = resize_v1(env, 84, 84)  # Then resize
```

--------------------------------

### Vectorized Environment for Performance

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/00_overview.md

This example contrasts sequential environment stepping with vectorized stepping for performance gains. It shows how to create a vectorized environment using `gym_vec_env_v0` for batch processing of environments.

```python
# Slow: Sequential
for i in range(1000):
    obs, rew, term, trunc, info = env.step(action)

# Fast: Vectorized (8 envs in parallel)
vec_env = gym_vec_env_v0(env, 8, multiprocessing=True)
obs, rew, term, trunc, info = vec_env.step(actions)
```

--------------------------------

### Vectorized Training with Stable-Baselines3 and Supersuit

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/README.md

Shows how to create a vectorized environment using Supersuit's `stable_baselines3_vec_env_v0` wrapper for efficient training with Stable-Baselines3. This example uses the CartPole environment.

```python
from stable_baselines3 import PPO
from supersuit import stable_baselines3_vec_env_v0

env = gymnasium.make('CartPole-v1')
vec_env = stable_baselines3_vec_env_v0(env, num_envs=8, multiprocessing=True)

agent = PPO('MlpPolicy', vec_env)
agent.learn(total_timesteps=100000)
```

--------------------------------

### Create Stable Baselines3 Vector Environment and Train Agent

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/04_vector_environments.md

Creates a synchronous or asynchronous Stable Baselines3 vector environment, recommended for RL training. This example demonstrates training a PPO agent with the created vector environment.

```python
import gymnasium
from stable_baselines3 import PPO
from supersuit import stable_baselines3_vec_env_v0

env = gymnasium.make('CartPole-v1')
vec_env = stable_baselines3_vec_env_v0(env, num_envs=4, multiprocessing=True)

# Train agent
agent = PPO('MlpPolicy', vec_env, verbose=1)
agent.learn(total_timesteps=10000)
```

--------------------------------

### Apply Logarithmic Reward Scaling

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/02_lambda_wrappers.md

This example demonstrates using reward_lambda_v0 with a logarithmic scaling function for rewards, suitable for environments with highly variable reward magnitudes like Atari games.

```python
import gymnasium
import numpy as np
from supersuit import reward_lambda_v0

env = gymnasium.make('Atari/Pong-v5')

def log_reward(rew):
    return np.sign(rew) * np.log1p(np.abs(rew))

env = reward_lambda_v0(env, log_reward)
```

--------------------------------

### Stateless Wrapper Example: Clip Actions

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/09_architecture_guide.md

A stateless wrapper that clips actions to a specified range. It modifies the action in the step function without maintaining internal state beyond configuration.

```python
class clip_actions_wrapper:
    def __init__(self, clip_value):
        self.clip_value = clip_value
    
    def step(self, action):
        action = np.clip(action, -self.clip_value, self.clip_value)
        return super().step(action)
```

--------------------------------

### UserWarning: NaN Action Handling

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/07_errors.md

Shows example warning messages for NaN or None actions encountered by `nan_random_v0`, `nan_noop_v0`, or `nan_zeros_v0`.

```python
[WARNING]: Step received an NaN action {}. Environment is {}. Taking a random action.
```

```python
[WARNING]: Step received an None action {}. Environment is {}. Taking [action type].
```

--------------------------------

### Stateful Wrapper Example: Frame Stack Initialization

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/09_architecture_guide.md

A stateful wrapper that initializes its internal state, such as a frame stack, during the reset phase. This ensures the state is correctly sized and cleared for each new episode.

```python
class frame_stack_wrapper:
    def __init__(self, stack_size):
        self.stack_size = stack_size
    
    def reset(self, seed=None, options=None):
        # Initialize stack
        self.stack = np.zeros((stack_size, *obs_shape))
        return super().reset(seed, options)
    
    def step(self, action):
        obs, ... = super().step(action)
        self.stack = self._add_to_stack(obs)
        return self.stack, ...
```

--------------------------------

### Custom Lambda Transformations for Observations and Rewards

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/00_overview.md

Apply custom transformations to observations and rewards using lambda functions with SuperSuit's lambda wrappers. This example doubles observations and clips rewards.

```python
from supersuit import observation_lambda_v0, reward_lambda_v0

env = gymnasium.make('CartPole-v1')

# Double observations
env = observation_lambda_v0(env, lambda obs, obs_space: obs * 2)

# Clip rewards
env = reward_lambda_v0(env, lambda rew: max(min(rew, 1), -1))

obs, info = env.reset()
```

--------------------------------

### Custom Transformations with Lambda Wrappers

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/README.md

Applies custom transformations to observations and rewards using lambda functions. This is useful for applying specific, user-defined modifications to environment outputs. Ensure SuperSuit is installed.

```python
from supersuit import observation_lambda_v0, reward_lambda_v0

env = gymnasium.make('CartPole-v1')
env = observation_lambda_v0(env, lambda obs, obs_space: obs * 2)
env = reward_lambda_v0(env, lambda rew: max(min(rew, 1), -1))
```

--------------------------------

### Per-Agent State Wrapper Example: Frame Stack AEC

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/09_architecture_guide.md

An AEC wrapper that manages per-agent state, specifically frame stacks. It initializes and updates these stacks for each agent dynamically, accommodating potential agent additions or removals.

```python
class frame_stack_aec_wrapper:
    def reset(self, seed=None, options=None):
        super().reset(seed, options)
        # Create per-agent state
        self.stacks = {
            agent: np.zeros((stack_size, *shape))
            for agent in self.agents
        }
    
    def step(self, action):
        agent = self.agent_selection
        self.stacks[agent] = self._add_to_stack(self.stacks[agent], action)
        super().step(action)
```

--------------------------------

### BaseModifier Usage Example

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/08_utilities_and_internals.md

Example of creating a custom modifier to double observations. This modifier can then be used with the shared_wrapper function.

```python
from supersuit.generic_wrappers.utils.base_modifier import BaseModifier
from supersuit.generic_wrappers.utils.shared_wrapper_util import shared_wrapper

class DoubleObsModifier(BaseModifier):
    def modify_obs(self, obs):
        return obs * 2.0

def double_obs_v0(env):
    return shared_wrapper(env, DoubleObsModifier)

# Use it
import gymnasium
env = gymnasium.make('CartPole-v1')
env = double_obs_v0(env)
obs, info = env.reset()
# obs is doubled
```

--------------------------------

### Catch DeprecatedWrapper Exception

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/07_errors.md

Example of how to catch the DeprecatedWrapper exception when importing a deprecated wrapper version.

```python
from supersuit import DeprecatedWrapper

try:
    from supersuit import concat_vec_envs_v0
except DeprecatedWrapper as e:
    print(f"Error: {e}")
    # Output: concat_vec_envs_v0 is now deprecated, use concat_vec_envs_v1 instead
```

--------------------------------

### Vector Environment with Stable Baselines3 Wrapper

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/04_vector_environments.md

Shows how to create a vectorized environment and wrap it specifically for use with the Stable Baselines3 library, enabling agent training.

```python
import gymnasium
from stable_baselines3 import PPO
from supersuit import gym_vec_env_v0, concat_vec_envs_v1

env = gymnasium.make('CartPole-v1')
vec_env = gym_vec_env_v0(env, num_envs=4)

# Wrap for Stable Baselines3
concat_env = concat_vec_envs_v1(
    vec_env,
    num_vec_envs=2,
    num_cpus=0,
    base_class="stable_baselines3"
)

agent = PPO('MlpPolicy', concat_env)
```

--------------------------------

### Compose Multiple Multi-Agent Wrappers

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/03_multiagent_wrappers.md

Demonstrates the composition pattern for applying multiple multi-agent wrappers sequentially to handle heterogeneous environments. This includes homogenizing spaces, adding agent identification, and managing agent death.

```python
from pettingzoo.butterfly import pistonball_v0
from supersuit import (
    pad_observations_v0,
    pad_action_space_v0,
    agent_indicator_v0,
    black_death_v3
)

env = pistonball_v0.parallel_env()

# Homogenize spaces
env = pad_observations_v0(env)
env = pad_action_space_v0(env)

# Add agent identification
env = agent_indicator_v0(env, type_only=False)

# Handle death
env = black_death_v3(env)

obs, info = env.reset()
actions = {agent: env.action_space(agent).sample() for agent in env.agents}
obs, rew, term, trunc, info = env.step(actions)
```

--------------------------------

### NumPy ndarray Action Representation

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/06_types.md

Provides examples of NumPy ndarray and integer representations for actions, used in various SuperSuit transformations and vector environment operations.

```python
action: np.ndarray  # shape: (1,), dtype: float32
action: int  # For Discrete spaces
```

--------------------------------

### Create and Concatenate Vector Environments

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/04_vector_environments.md

Demonstrates creating a 4-environment vectorized environment and then concatenating it with 3 more copies to create a total of 12 environments. Shows how to reset the environment and inspect the observation shape.

```python
import gymnasium
from supersuit import gym_vec_env_v0, concat_vec_envs_v1

env = gymnasium.make('CartPole-v1')
vec_env = gym_vec_env_v0(env, num_envs=4)

# Concatenate 3 copies → 12 total environments
concat_env = concat_vec_envs_v1(vec_env, num_vec_envs=3, num_cpus=0)
print(concat_env.num_envs)  # 12

obs, info = concat_env.reset()
print(obs.shape)  # (12, 4)
```

--------------------------------

### Chaining Supersuit Wrappers

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/09_architecture_guide.md

Demonstrates composing multiple Supersuit wrappers to build a complex preprocessing pipeline. Wrappers are applied sequentially to modify the environment.

```python
env = resize_v1(env, 84, 84)
env = color_reduction_v0(env, 'full')
env = frame_stack_v1(env, 4)
env = normalize_obs_v0(env)
```

--------------------------------

### Accumulate Observations with Maximum

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/08_utilities_and_internals.md

Demonstrates accumulating observations using a specified function (np.maximum). The `get()` method returns the current accumulated value, which updates based on the `accumulate_fn` after each `add()` call.

```python
import numpy as np
from supersuit.utils.accumulator import Accumulator
import gymnasium

space = gymnasium.spaces.Box(0, 255, shape=(84, 84, 1), dtype=np.uint8)
acc = Accumulator(space, memory=2, accumulate_fn=np.maximum)

obs1 = np.ones((84, 84, 1), dtype=np.uint8) * 100
obs2 = np.ones((84, 84, 1), dtype=np.uint8) * 200

acc.add(obs1)
print(acc.get())  # array of 100s

acc.add(obs2)
print(acc.get())  # array of 200s (maximum)
```

--------------------------------

### Create and Inspect SyncAECVectorEnv

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/05_aec_vector_environments.md

Demonstrates how to create a synchronous AEC vector environment and inspect its properties. Use this for simpler parallelization where true parallelism is not strictly required.

```python
from pettingzoo.butterfly import pistonball_v0
from supersuit import vectorize_aec_env_v0

env = pistonball_v0.env()
vec_env = vectorize_aec_env_v0(env, num_envs=4, num_cpus=0)

print(type(vec_env).__name__)  # SyncAECVectorEnv
print(vec_env.num_envs)  # 4
print(vec_env.possible_agents)  # All agent names
```

--------------------------------

### Create and Inspect AsyncAECVectorEnv

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/05_aec_vector_environments.md

Shows how to create an asynchronous AEC vector environment using subprocesses for true parallelism. This is more efficient for CPU-bound simulations.

```python
from pettingzoo.butterfly import pistonball_v0
from supersuit import vectorize_aec_env_v0

env = pistonball_v0.env()
vec_env = vectorize_aec_env_v0(env, num_envs=4, num_cpus=2)

print(type(vec_env).__name__)  # AsyncAECVectorEnv

# Same usage as SyncAECVectorEnv
vec_env.reset()
for agent in vec_env.agent_iter(max_iter=1000):
    obs = vec_env.observe(agent)
    actions = [vec_env.action_space(agent).sample() for _ in range(4)]
    vec_env.step(actions)
```

--------------------------------

### Compose Multiple Lambda Wrappers

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/02_lambda_wrappers.md

Demonstrates composing observation, action, and reward lambda wrappers to sequentially transform different aspects of the environment. This allows for complex pre-processing pipelines.

```python
import gymnasium
from supersuit import (
    observation_lambda_v0,
    action_lambda_v1,
    reward_lambda_v0
)

env = gymnasium.make('CartPole-v1')

# Transform observations
env = observation_lambda_v0(
    env,
    lambda obs, obs_space: obs.astype('float32') / 100.0
)

# Transform actions
env = action_lambda_v1(
    env,
    lambda action, action_space: action,
    lambda action_space: action_space
)

# Transform rewards
env = reward_lambda_v0(
    env,
    lambda rew: rew * 0.1
)

obs, info = env.reset()
```

--------------------------------

### Vectorize Gymnasium Environment with Multiprocessing

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/04_vector_environments.md

Demonstrates vectorizing a single Gymnasium environment using `gym_vec_env_v0` with multiprocessing enabled for potentially faster execution. Shows basic usage including reset and stepping through episodes.

```python
import gymnasium
from supersuit import gym_vec_env_v0

# Create single environment
env = gymnasium.make('Atari/Pong-v5')

# Vectorize
vec_env = gym_vec_env_v0(env, num_envs=8, multiprocessing=True)

# Use like normal vector environment
obs, info = vec_env.reset(seed=42)

for _ in range(1000):
    actions = vec_env.action_space.sample()
    obs, rewards, terminations, truncations, infos = vec_env.step(actions)
    
    # Automatic reset on episode termination
    if terminations.any():
        # Some envs terminated; gymnasium handles reset internally
        pass
```

--------------------------------

### Multi-Agent Preprocessing with Supersuit

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/00_overview.md

This snippet demonstrates how to apply several preprocessing wrappers to a PettingZoo environment for multi-agent scenarios. It pads observations and action spaces, and adds an agent indicator.

```python
from pettingzoo.butterfly import pistonball_v0
from supersuit import pad_observations_v0, pad_action_space_v0, agent_indicator_v0

env = pistonball_v0.parallel_env()
env = pad_observations_v0(env)
env = pad_action_space_v0(env)
env = agent_indicator_v0(env, type_only=False)

obs, info = env.reset()
```

--------------------------------

### Get Last State in Vectorized AEC Environment

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/05_aec_vector_environments.md

Retrieve the last state information (observations, rewards, dones, etc.) for all environments for the current agent. Set `observe=False` to omit observations for efficiency.

```python
obs, rewards, dones, env_dones, passes, infos = vec_env.last()
print(rewards.shape)  # (4,)
print(dones.dtype)  # bool
```

--------------------------------

### Import All Public Wrappers

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/00_overview.md

Import all available public wrappers from the main supersuit module. This includes generic, lambda, and multi-agent wrappers, as well as vector constructors.

```python
from supersuit import (
    # Generic wrappers
    color_reduction_v0,
    frame_stack_v1,
    frame_stack_v2,
    resize_v1,
    flatten_v0,
    normalize_obs_v0,
    clip_actions_v0,
    clip_reward_v0,
    frame_skip_v0,
    sticky_actions_v0,
    delay_observations_v0,
    max_observation_v0,
    dtype_v0,
    reshape_v0,
    scale_actions_v0,
    nan_random_v0,
    nan_noop_v0,
    nan_zeros_v0,
    
    # Lambda wrappers
    observation_lambda_v0,
    action_lambda_v1,
    reward_lambda_v0,
    
    # Multi-agent wrappers
    pad_observations_v0,
    pad_action_space_v0,
    agent_indicator_v0,
    black_death_v3,
    
    # Vector constructors
    gym_vec_env_v0,
    stable_baselines3_vec_env_v0,
    stable_baselines_vec_env_v0,
    concat_vec_envs_v1,
    pettingzoo_env_to_vec_env_v1,
    
    # AEC vector
    vectorize_aec_env_v0,
)
```

--------------------------------

### Create Gymnasium Vector Environment

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/04_vector_environments.md

Creates a synchronous or asynchronous Gymnasium vector environment from a template Gymnasium environment. Use `multiprocessing=True` for asynchronous execution with process pools.

```python
import gymnasium
from supersuit import gym_vec_env_v0

env = gymnasium.make('CartPole-v1')
vec_env = gym_vec_env_v0(env, num_envs=4, multiprocessing=False)

obs, info = vec_env.reset()
print(obs.shape)  # (4, 4) for 4 vectorized CartPole envs

actions = vec_env.action_space.sample()
obs, rew, term, trunc, info = vec_env.step(actions)
print(rew.shape)  # (4,)
```

--------------------------------

### Environment Cloning with Cloudpickle

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/04_vector_environments.md

Illustrates the use of `cloudpickle` for cloning environments, ensuring that each vectorized instance maintains independent state.

```python
import cloudpickle

def env_fn():
    return cloudpickle.loads(cloudpickle.dumps(env))
```

--------------------------------

### Choosing Frame Stacking Wrapper Version

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/00_overview.md

This snippet explains the difference between `frame_stack_v1` and `frame_stack_v2`. `v1` gradually fills the stack over steps, while `v2` fills it immediately on reset by repeating the initial observation.

```python
# v1: Gradually fills stack (4 steps to fill)
env = frame_stack_v1(env, 4)

# v2: Stack filled immediately (same obs repeated)
env = frame_stack_v2(env, 4)
```

--------------------------------

### Create Stable Baselines Vector Environment

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/04_vector_environments.md

Creates a synchronous or asynchronous Stable Baselines vector environment. Note that Stable Baselines is a legacy library.

```python
import gymnasium
from supersuit import stable_baselines_vec_env_v0

env = gymnasium.make('CartPole-v1')
vec_env = stable_baselines_vec_env_v0(env, num_envs=4, multiprocessing=False)
```

--------------------------------

### Homogenize Action Spaces with Pad Action Space Wrapper

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/03_multiagent_wrappers.md

Utilize pad_action_space_v0 to make all agents' action spaces uniform. This wrapper computes the maximum bounds across all agent action spaces and adjusts the wrapper's action space accordingly, while also clipping actions to original agent spaces.

```python
from pettingzoo.butterfly import pistonball_v0
from supersuit import pad_action_space_v0

env = pistonball_v0.parallel_env()
env = pad_action_space_v0(env)

# All agents can now receive actions of the same size
for agent in env.agents:
    print(agent, env.action_space(agent))  # All identical
```

--------------------------------

### stable_baselines3_vec_env_v0

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/04_vector_environments.md

Creates a vector environment compatible with Stable Baselines3, recommended for modern RL training. Supports synchronous and asynchronous execution.

```APIDOC
## stable_baselines3_vec_env_v0

### Description
Creates a Stable Baselines3 vector environment, recommended for RL training. Supports synchronous and asynchronous execution.

### Method
`stable_baselines3_vec_env_v0(env, num_envs, multiprocessing=False)`

### Parameters
#### Path Parameters
- **env** (gymnasium.Env) - Required - Template Gymnasium environment to vectorize
- **num_envs** (int) - Required - Number of parallel environments
- **multiprocessing** (bool) - Optional - If True, use SubprocVecEnv; if False, use DummyVecEnv. Defaults to False.

### Returns
- `stable_baselines3.common.vec_env.DummyVecEnv` or `stable_baselines3.common.vec_env.SubprocVecEnv`

### Returns
- DummyVecEnv (multiprocessing=False): Synchronous vectorized wrapper
- SubprocVecEnv (multiprocessing=True): Asynchronous with subprocess pool

### Example
```python
import gymnasium
from stable_baselines3 import PPO
from supersuit import stable_baselines3_vec_env_v0

env = gymnasium.make('CartPole-v1')
vec_env = stable_baselines3_vec_env_v0(env, num_envs=4, multiprocessing=True)

# Train agent
agent = PPO('MlpPolicy', vec_env, verbose=1)
agent.learn(total_timesteps=10000)
```
```

--------------------------------

### Gymnasium Environment Preprocessing

Source: https://github.com/farama-foundation/supersuit/blob/main/README.md

Applies color reduction and frame stacking to a Gymnasium environment. Use this to prepare observations for reinforcement learning agents.

```python
import gymnasium
from supersuit import color_reduction_v0, frame_stack_v1

env = gymnasium.make('SpaceInvaders-v0')

env = frame_stack_v1(color_reduction_v0(env, 'full'), 4)
```

--------------------------------

### Vectorization Pipeline with gym_vec_env_v0

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/09_architecture_guide.md

Creates a vectorized environment from a single Gymnasium environment. It clones the environment multiple times and stacks observations for parallel processing.

```python
env = gymnasium.make('CartPole-v1')
vec_env = gym_vec_env_v0(env, num_envs=4)
obs, info = vec_env.reset()
```

--------------------------------

### Scale Actions by a Factor

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/01_generic_wrappers.md

Wraps an environment to scale action values by a constant factor. This is useful for adjusting the magnitude of actions, particularly for environments with Box action spaces.

```python
import gymnasium
import numpy as np
from supersuit import scale_actions_v0

env = gymnasium.make('Pendulum-v1')
env = scale_actions_v0(env, 0.5)
obs, info = env.reset()
action = np.array([1.0])  # Applied as 0.5
```

--------------------------------

### Implement Frame Skipping

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/01_generic_wrappers.md

Wraps an environment to repeat actions for a specified number of frames, accumulating rewards over those frames. Supports fixed or random frame skips.

```python
import gymnasium
from supersuit import frame_skip_v0

env = gymnasium.make('Atari/SpaceInvaders-v5')
env = frame_skip_v0(env, 4)  # Fixed 4-frame skip
obs, info = env.reset()

# Each step repeats the action for 4 frames
obs, rew, term, trunc, info = env.step(env.action_space.sample())
```

--------------------------------

### gym_vec_env_v0

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/04_vector_environments.md

Creates a Gymnasium vector environment from a Gymnasium environment. It supports both synchronous and asynchronous (multiprocessing) vectorized environments.

```APIDOC
## gym_vec_env_v0

### Description
Creates a Gymnasium vector environment from a Gymnasium environment. Supports synchronous and asynchronous execution.

### Method
`gym_vec_env_v0(env, num_envs, multiprocessing=False)`

### Parameters
#### Path Parameters
- **env** (gymnasium.Env) - Required - Template Gymnasium environment to vectorize (must inherit from gymnasium.Env)
- **num_envs** (int) - Required - Number of parallel environments to create
- **multiprocessing** (bool) - Optional - If True, use AsyncVectorEnv (multiprocessing); if False, use SyncVectorEnv (synchronous). Defaults to False.

### Returns
- `gymnasium.vector.SyncVectorEnv` or `gymnasium.vector.AsyncVectorEnv`

### Raises
- Warning: If env does not inherit from gymnasium.Env

### Example
```python
import gymnasium
from supersuit import gym_vec_env_v0

env = gymnasium.make('CartPole-v1')
vec_env = gym_vec_env_v0(env, num_envs=4, multiprocessing=False)

obs, info = vec_env.reset()
print(obs.shape)  # (4, 4) for 4 vectorized CartPole envs

actions = vec_env.action_space.sample()
obs, rew, term, trunc, info = vec_env.step(actions)
print(rew.shape)  # (4,)
```
```

--------------------------------

### Homogenize Observation Spaces with Pad Observations Wrapper

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/03_multiagent_wrappers.md

Employ pad_observations_v0 to ensure all agents have identical observation spaces and shapes. This wrapper analyzes all agent observation spaces and pads individual observations to match the largest observed space.

```python
from pettingzoo.butterfly import pistonball_v0
from supersuit import pad_observations_v0

env = pistonball_v0.parallel_env()
env = pad_observations_v0(env)

obs, info = env.reset()
# All agents have the same observation space and shape
for agent, ob in obs.items():
    print(agent, ob.shape)  # All shapes identical
```

--------------------------------

### PettingZoo Environment Preprocessing

Source: https://github.com/farama-foundation/supersuit/blob/main/README.md

Applies color reduction and frame stacking to a PettingZoo environment. This is useful for multi-agent reinforcement learning scenarios.

```python
from pettingzoo.butterfly import pistonball_v0
env = pistonball_v0.env()

env = frame_stack_v1(color_reduction_v0(env, 'full'), 4)
```

--------------------------------

### stable_baselines_vec_env_v0

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/04_vector_environments.md

Creates a vector environment compatible with the legacy Stable Baselines library. It can be configured for synchronous or asynchronous execution.

```APIDOC
## stable_baselines_vec_env_v0

### Description
Creates a Stable Baselines vector environment. Supports synchronous and asynchronous execution.

### Method
`stable_baselines_vec_env_v0(env, num_envs, multiprocessing=False)`

### Parameters
#### Path Parameters
- **env** (gymnasium.Env) - Required - Template Gymnasium environment to vectorize
- **num_envs** (int) - Required - Number of parallel environments
- **multiprocessing** (bool) - Optional - If True, use SubprocVecEnv; if False, use DummyVecEnv. Defaults to False.

### Returns
- `stable_baselines.common.vec_env.DummyVecEnv` or `stable_baselines.common.vec_env.SubprocVecEnv`

### Note
Stable Baselines is a legacy library. For new projects, use Stable Baselines3.

### Example
```python
import gymnasium
from supersuit import stable_baselines_vec_env_v0

env = gymnasium.make('CartPole-v1')
vec_env = stable_baselines_vec_env_v0(env, num_envs=4, multiprocessing=False)
```
```

--------------------------------

### Vectorizing AEC Environments with Supersuit

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/00_overview.md

This snippet demonstrates vectorizing a PettingZoo AEC environment using Supersuit. It applies preprocessing wrappers and then vectorizes the environment for parallel processing, suitable for training.

```python
from pettingzoo.butterfly import pistonball_v0
from supersuit import pad_observations_v0, pad_action_space_v0, vectorize_aec_env_v0

env = pistonball_v0.env()
env = pad_observations_v0(env)
env = pad_action_space_v0(env)
vec_env = vectorize_aec_env_v0(env, num_envs=4, num_cpus=0)

vec_env.reset()
for agent in vec_env.agent_iter(max_iter=1000):
    obs = vec_env.observe(agent)
    actions = [vec_env.action_space(agent).sample() for _ in range(4)]
    vec_env.step(actions)
```

--------------------------------

### Handling AssertionError for Incompatible Environment with black_death_v3

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/07_errors.md

Demonstrates catching an `AssertionError` when `black_death_v3` is applied to an incompatible environment.

```python
from pettingzoo.butterfly import pistonball_v0
from supersuit import black_death_v3

env = pistonball_v0.parallel_env()

try:
    env = black_death_v3(env)
except AssertionError as e:
    print(f"Environment not compatible with black_death: {e}")
    # Use different wrapper or preprocess environment
```

--------------------------------

### Replace NaN/None Actions with Zero Arrays

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/01_generic_wrappers.md

Wraps an environment to replace NaN or None actions with zero arrays. This provides a default action when invalid actions are detected.

```python
import gymnasium
from supersuit import nan_zeros_v0

env = gymnasium.make('Pendulum-v1')
env = nan_zeros_v0(env)
obs, info = env.reset()
```

--------------------------------

### PettingZoo AEC Wrapper Implementation Pattern

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/09_architecture_guide.md

Implement the agent-by-agent interface by inheriting from BaseWrapper. This pattern requires careful state management for per-agent data due to the agent cycling.

```python
class aec_my_wrapper(BaseWrapper):
    def _modify_observation(self, agent, observation):
        return transform(observation)
    
    def _modify_action(self, agent, action):
        return transform(action)
    
    def _modify_spaces(self):
        # Called during initialization
        pass
```

--------------------------------

### Convert PettingZoo Parallel Env to Gymnasium Vector Env

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/04_vector_environments.md

Converts a multi-agent PettingZoo parallel environment into a single-agent Gymnasium vector environment. Ensures homogeneous observation and action spaces before conversion.

```python
from pettingzoo.butterfly import pistonball_v0
from supersuit import pad_observations_v0, pad_action_space_v0, pettingzoo_env_to_vec_env_v1

# Create multi-agent environment
env = pistonball_v0.parallel_env()

# Ensure homogeneous spaces
env = pad_observations_v0(env)
env = pad_action_space_v0(env)

# Convert to vector environment
vec_env = pettingzoo_env_to_vec_env_v1(env)
print(vec_env.num_envs)  # Number of agents in pistonball

obs, info = vec_env.reset()
actions = vec_env.action_space.sample()
obs, rew, term, trunc, info = vec_env.step(actions)
```

--------------------------------

### Replace NaN Actions with Random Actions

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/01_generic_wrappers.md

Wraps an environment to replace NaN actions with random actions sampled from the action space. Issues a warning when NaN actions are encountered. If the environment has an action mask, it samples from valid actions; otherwise, it samples uniformly.

```python
import gymnasium
import numpy as np
from supersuit import nan_random_v0

env = gymnasium.make('CartPole-v1')
env = nan_random_v0(env)
obs, info = env.reset()
```

--------------------------------

### PettingZoo Parallel Wrapper Implementation Pattern

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/09_architecture_guide.md

Implement the dictionary interface by inheriting from BaseParallelWrapper. This pattern allows for simultaneous agent steps and batch operations, mapping naturally to vectorization.

```python
class parallel_my_wrapper(BaseParallelWrapper):
    def step(self, actions):
        obs, rew, term, trunc, info = super().step(actions)
        # Transform all observations at once
        obs = {agent: transform(obs[agent]) for agent in obs}
        return obs, rew, term, trunc, info
```

--------------------------------

### WrapperChooser for Environment Type Selection

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/09_architecture_guide.md

Automatically selects the correct wrapper implementation (Gymnasium, AECEnv, or ParallelEnv) based on the input environment type. This pattern simplifies the user API by providing a single import path and abstracting away implementation details.

```python
from supersuit.utils.wrapper_chooser import WrapperChooser

# Define three implementations
class gym_wrapper(gymnasium.Wrapper):
    def __init__(self, env):
        super().__init__(env)
        # Gymnasium-specific logic

class aec_wrapper(BaseWrapper):
    def __init__(self, env):
        super().__init__(env)
        # AEC-specific logic

class parallel_wrapper(BaseParallelWrapper):
    def __init__(self, env):
        super().__init__(env)
        # Parallel-specific logic

# Create wrapper selector
my_wrapper = WrapperChooser(
    gym_wrapper=gym_wrapper,
    aec_wrapper=aec_wrapper,
    parallel_wrapper=parallel_wrapper
)

# Use like a normal function
env = my_wrapper(original_env)  # Automatically picks right implementation
```

--------------------------------

### UserWarning: Vector Environment Compatibility

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/07_errors.md

Illustrates a warning message issued by vector constructors when an environment does not inherit from `gymnasium.Env`.

```python
{fn_name} took in an environment which does not inherit from gymnasium.Env...
```

--------------------------------

### Create Defaultdict with Default Values

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/08_utilities_and_internals.md

Use this function to create a defaultdict where specific keys return predefined default values. Keys not present in the defaults dictionary will return 0.0.

```python
from supersuit.utils.make_defaultdict import make_defaultdict

defaults = {'agent_0': 0.0, 'agent_1': 0.0}
rewards = make_defaultdict(defaults)

rewards['agent_0'] += 1.0
rewards['agent_2'] = 0.0  # Key not in defaults returns 0.0
```

--------------------------------

### Clip Rewards to a Range

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/01_generic_wrappers.md

Wraps an environment to clip rewards, ensuring they fall within a specified lower and upper bound (defaulting to -1 and 1). This can help stabilize training by preventing extreme reward values.

```python
import gymnasium
from supersuit import clip_reward_v0

env = gymnasium.make('Atari/Pong-v5')
env = clip_reward_v0(env, lower_bound=-1, upper_bound=1)
obs, info = env.reset()
obs, rew, term, trunc, info = env.step(env.action_space.sample())
print(-1 <= rew <= 1)  # True
```

--------------------------------

### Gymnasium Vector Environment Interface

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/09_architecture_guide.md

Defines the interface for Gymnasium's vectorized environments, including methods for resetting and stepping through environments.

```python
class gymnasium.vector.VectorEnv:
    num_envs: int
    observation_space: Space
    action_space: Space
    
    reset(seed, options) → (observations, infos)
    step(actions) → (observations, rewards, terminations, truncations, infos)
    step_async(actions) → None
    step_wait() → (observations, rewards, terminations, truncations, infos)
```

--------------------------------

### Multi-Agent Observation Space Padding with pad_observations_v0

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/09_architecture_guide.md

Pads observations for multi-agent environments to ensure uniform space sizes. It analyzes agent spaces and applies padding within a lambda wrapper.

```python
env = pistonball_v0.parallel_env()
env = pad_observations_v0(env)
obs, info = env.reset()
```

--------------------------------

### Gymnasium Wrapper Implementation Pattern

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/09_architecture_guide.md

Inherit from gymnasium.Wrapper and override step(), reset(), and modify observation_space/action_space properties. This pattern offers minimal overhead and direct compatibility with libraries like stable-baselines3.

```python
class gym_my_wrapper(gymnasium.Wrapper):
    def __init__(self, env):
        super().__init__(env)
        self.observation_space = new_space
        self.action_space = new_space
    
    def step(self, action):
        obs, rew, term, trunc, info = super().step(action)
        return transform(obs), rew, term, trunc, info
    
    def reset(self, seed=None, options=None):
        obs, info = super().reset(seed=seed, options=options)
        return transform(obs), info
```

--------------------------------

### pad_action_space_v0

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/03_multiagent_wrappers.md

Pads action spaces to make all agents' action spaces homogeneous. This is useful when agents have different action spaces, allowing all agents to receive actions of the same size.

```APIDOC
## pad_action_space_v0

### Description
Pads action spaces to make all agents' action spaces homogeneous. This is useful when agents have different action spaces, allowing all agents to receive actions of the same size.

### Method
`pad_action_space_v0(env)`

### Parameters
#### Path Parameters
- **env** (PettingZoo.AECEnv or ParallelEnv) - Required - Multi-agent environment to wrap

### Return type
Wrapped environment with homogenized action spaces

### Behavior
- Analyzes all agents' action spaces from `env.possible_agents`
- Computes the maximum bounds across all agents
- Pads the wrapper's action space to match the largest agent action space
- Automatically clips/dehomogenizes actions to each agent's original space

### Raises
- AssertionError: If environment lacks `possible_agents` attribute

### Example
```python
from pettingzoo.butterfly import pistonball_v0
from supersuit import pad_action_space_v0

env = pistonball_v0.parallel_env()
env = pad_action_space_v0(env)

# All agents can now receive actions of the same size
for agent in env.agents:
    print(agent, env.action_space(agent))  # All identical
```
```

--------------------------------

### Gymnasium Environment Type Signature

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/06_types.md

Illustrates the type signature for a Gymnasium environment, commonly used in vector constructors and generic wrappers.

```python
def gym_vec_env_v0(env: gymnasium.Env, num_envs: int, multiprocessing: bool = False)
```

--------------------------------

### Sticky Actions

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/01_generic_wrappers.md

Repeats the previous action with a specified probability. This wrapper can be used to simulate environments where actions might not be perfectly registered.

```python
import gymnasium
from supersuit import sticky_actions_v0

env = gymnasium.make('Atari/Pong-v5')
env = sticky_actions_v0(env, repeat_action_probability=0.25)
obs, info = env.reset()
```

--------------------------------

### sticky_actions_v0

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/01_generic_wrappers.md

Repeats the previous action with a specified probability. This wrapper can introduce stochasticity in action selection, mimicking real-world scenarios where actions might not always be perfectly executed.

```APIDOC
## sticky_actions_v0

### Description
Repeats the previous action with a specified probability.

### Method
POST

### Endpoint
/sticky_actions_v0

### Parameters
#### Request Body
- **env** (Gymnasium.Env or PettingZoo.AECEnv or ParallelEnv) - Required - The environment to wrap.
- **repeat_action_probability** (float) - Required - Probability in [0, 1) of repeating the previous action.

### Request Example
```python
{
  "env": "gymnasium.make('Atari/Pong-v5')",
  "repeat_action_probability": 0.25
}
```

### Response
#### Success Response (200)
- Wrapped environment with sticky actions

#### Response Example
```json
{
  "message": "Environment wrapped successfully"
}
```
```

--------------------------------

### Clip Actions within Action Space Bounds

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/01_generic_wrappers.md

Wraps an environment to clip continuous actions, ensuring they stay within the environment's action space bounds. This is crucial for environments with Box action spaces where actions might exceed limits.

```python
import gymnasium
import numpy as np
from supersuit import clip_actions_v0

env = gymnasium.make('Pendulum-v1')
env = clip_actions_v0(env)
obs, info = env.reset()
action = np.array([5.0])  # Outside bounds
obs, rew, term, trunc, info = env.step(action)  # Clipped to [-2, 2]
```

--------------------------------

### Catching AssertionError for Invalid Resize Parameters

Source: https://github.com/farama-foundation/supersuit/blob/main/_autodocs/07_errors.md

Demonstrates how to catch an `AssertionError` when providing invalid (negative) size parameters to `resize_v1`.

```python
import gymnasium
from supersuit import resize_v1

env = gymnasium.make('Atari/Pong-v5')

try:
    # This will fail: x_size must be positive int
    env = resize_v1(env, -1, 84)
except AssertionError as e:
    print(f"Invalid resize parameters: {e}")
```