Principle:Farama Foundation Gymnasium Space Abstraction

Knowledge Sources	Farama_Foundation_Gymnasium Gymnasium Docs
Domains	Reinforcement_Learning, API_Design
Last Updated	2026-02-15 03:00 GMT

Overview

An abstract base class for defining observation and action spaces provides a unified interface for sampling, containment checking, and structural transformations across all environment types.

Description

The Space abstraction is the foundational metaclass from which all observation and action space types inherit. It defines the contract that every space must fulfill: specifying a shape, a data type, a random number generator for sampling, and methods for checking membership, sampling elements, and converting to/from serializable representations. This uniform interface enables RL algorithms, wrappers, and utilities to operate generically over any space type without needing to know the specific subclass.

The Space base class is complemented by a set of utility functions that perform structural transformations on spaces. The flatten and unflatten utilities convert between structured space elements and flat numpy arrays, which is essential for feeding observations into neural networks that expect fixed-size vector inputs. The flatdim function computes the dimensionality of the flattened representation. Additional vector utilities handle batching and unbatching of space elements for vectorized (multi-environment) settings, including batch_space, iterate, concatenate, and create_empty_array.

Together, the Space base class and its utility functions form the type system of the RL environment interface. They ensure that observations and actions are well-typed, that random exploration is always available via sampling, and that any space can be transformed for consumption by learning algorithms. This architecture supports both simple spaces (Box, Discrete) and complex composite spaces (Dict, Tuple, Graph) through a consistent polymorphic API.

Usage

Use the Space abstraction when defining custom observation or action spaces for new environments. Inherit from Space and implement the required methods (sample, contains, __repr__, __eq__) to create a new space type. Use the utility functions (flatten, unflatten, flatdim) when converting structured observations into flat arrays for neural network input. Use the vector utility functions (batch_space, iterate, concatenate) when implementing or working with vectorized environments that process multiple environment instances in parallel.

Theoretical Basis

The Space abstraction formalizes the mathematical concept of the observation space $𝒪$ and action space $𝒜$ in a Markov Decision Process. Every space must support:

Sampling: $x \sim p (𝒮)$ where $p$ is a distribution over the space
Containment: $x \in 𝒮$ returns a boolean
Flattening: $flat : 𝒮 \to ℝ^{d}$ where $d = flatdim (𝒮)$
Unflattening: $unflat : ℝ^{d} \to 𝒮$ is the inverse of flattening

The flatdim function computes $d$ recursively for composite spaces:

$flatdim (Tuple (S_{1}, \dots, S_{n})) = \sum_{i = 1}^{n} flatdim (S_{i})$

$flatdim (Dict ({k_{1} : S_{1}, \dots, k_{n} : S_{n}})) = \sum_{i = 1}^{n} flatdim (S_{i})$

For vector environments, the batch_space operation creates a batched version of a space:

# Space base class contract
class Space:
    shape: tuple         # shape of elements
    dtype: np.dtype      # data type of elements
    np_random: Generator # seeded random number generator

    def sample(mask=None) -> element    # draw random element
    def contains(x) -> bool             # check membership
    def seed(seed) -> list[int]         # seed the RNG

# Utility functions
flat_obs = flatten(space, obs)          # structured -> flat array
obs = unflatten(space, flat_obs)        # flat array -> structured
d = flatdim(space)                      # dimensionality of flat repr

# Vector utilities
batched_space = batch_space(space, n)   # single -> batched space
elements = iterate(space, batched_x)    # split batch into elements
batched_x = concatenate(space, elems)   # merge elements into batch

The Space class uses lazy initialization of the random number generator via a property that calls the seeding utility only when sampling is first requested.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment