Implementation:Farama Foundation Gymnasium Vector Space Utils
| Knowledge Sources | |
|---|---|
| Domains | Reinforcement_Learning, Vector_Environments |
| Last Updated | 2026-02-15 03:00 GMT |
Overview
Provides space manipulation utilities for vectorized environments including batching spaces, iterating over batched samples, concatenating samples, and creating empty arrays.
Description
The space_utils module implements five core functions used by Gymnasium's vectorized environment infrastructure, all implemented as functools.singledispatch functions with specializations for each space type:
batch_space(space, n) creates a batched version of a space by adding an outer dimension of size n. For example, a Discrete(5) becomes MultiDiscrete([5, 5, ..., 5]) with n elements, a Box gets an extra leading dimension via np.tile, and MultiBinary/MultiDiscrete are converted to equivalent Box spaces. Composite spaces (Tuple, Dict) are batched recursively. Non-standard spaces (Graph, Text, Sequence, OneOf) are wrapped in a Tuple of n deep copies.
batch_differing_spaces(spaces) batches a sequence of spaces that share the same type but may have different parameters (e.g., different n values for Discrete spaces). For example, [Discrete(3), Discrete(5)] becomes MultiDiscrete([3, 5]).
iterate(space, items) yields individual unbatched samples from a batched sample. For base spaces (Box, MultiDiscrete, MultiBinary) it uses iter(items). For Dict spaces it yields dictionaries with individual values. Discrete spaces raise TypeError since they cannot be iterated.
concatenate(space, items, out) stacks multiple unbatched samples into a batched array, using np.stack for base spaces and recursive concatenation for composite spaces.
create_empty_array(space, n, fn) creates an empty array (default np.zeros) suitable for use as the out parameter of concatenate. Handles all space types including Graph (returns tuples of GraphInstance), Text (returns character strings), and Sequence.
Usage
These functions are used internally by SyncVectorEnv and AsyncVectorEnv to manage batched observation and action spaces. They can also be used directly when building custom vectorized environment implementations.
Code Reference
Source Location
- Repository: Farama_Foundation_Gymnasium
- File:
gymnasium/vector/utils/space_utils.py
Signature
@singledispatch
def batch_space(space: Space[Any], n: int = 1) -> Space[Any]
@singledispatch
def batch_differing_spaces(spaces: Sequence[Space]) -> Space
@singledispatch
def iterate(space: Space[T_cov], items: T_cov) -> Iterator
@singledispatch
def concatenate(space: Space, items: Iterable, out: Any) -> Any
@singledispatch
def create_empty_array(space: Space, n: int = 1, fn: Callable = np.zeros) -> Any
Import
from gymnasium.vector.utils import batch_space, iterate, concatenate, create_empty_array
from gymnasium.vector.utils.space_utils import batch_differing_spaces
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| space | gymnasium.Space | Yes | The space to batch, iterate, concatenate, or create empty arrays for |
| n | int | No | Number of environments / batch size (default 1) |
| items | Iterable | Yes (for concatenate, iterate) | Samples to concatenate or batched items to iterate |
| out | np.ndarray or nested | Yes (for concatenate) | Pre-allocated output array from create_empty_array |
| fn | Callable | No | Array creation function (default np.zeros) |
| spaces | Sequence[Space] | Yes (for batch_differing_spaces) | Sequence of compatible spaces to batch |
Outputs
| Name | Type | Description |
|---|---|---|
| batched_space | Space | A batched version of the input space (from batch_space) |
| iterator | Iterator | Iterator over individual samples (from iterate) |
| concatenated | np.ndarray or nested | Stacked samples (from concatenate) |
| empty_array | np.ndarray or nested | Pre-allocated empty array (from create_empty_array) |
Usage Examples
from gymnasium.spaces import Box, Dict
from gymnasium.vector.utils import batch_space, iterate, concatenate, create_empty_array
import numpy as np
# Batch a Dict space for 5 environments
space = Dict({
'position': Box(low=0, high=1, shape=(3,), dtype=np.float32),
'velocity': Box(low=0, high=1, shape=(2,), dtype=np.float32),
})
batched = batch_space(space, n=5)
# Dict('position': Box(0.0, 1.0, (5, 3), float32), 'velocity': Box(0.0, 1.0, (5, 2), float32))
# Create empty output array
out = create_empty_array(Box(low=0, high=1, shape=(3,), dtype=np.float32), n=4)
# array([[0., 0., 0.], [0., 0., 0.], [0., 0., 0.], [0., 0., 0.]], dtype=float32)
# Concatenate samples
single_space = Box(low=0, high=1, shape=(3,), seed=42, dtype=np.float32)
samples = [single_space.sample() for _ in range(4)]
result = concatenate(single_space, samples, out)
# Iterate over batched items
batched_space = Box(low=0, high=1, shape=(3, 2), seed=42, dtype=np.float32)
items = batched_space.sample()
for item in iterate(batched_space, items):
print(item.shape) # (2,)