Principle:Farama Foundation Gymnasium Composite Space Types

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

Overview

Advanced space types represent structured, variable-length, or graph-based observations and actions that go beyond simple continuous or discrete primitives.

Description

Composite space types extend the basic continuous (Box) and discrete (Discrete) space primitives to handle the rich data structures encountered in real-world reinforcement learning problems. These spaces can represent multi-dimensional binary vectors, multi-dimensional discrete vectors, graph-structured data with variable-length node and edge features, variable-length sequences, textual data, heterogeneous tuples of sub-spaces, and mutually exclusive choice spaces.

Each composite space type addresses a specific structural need. MultiBinary represents fixed-length binary vectors (useful for multi-label actions). MultiDiscrete represents vectors where each element has its own discrete range (useful for factored action spaces). Graph encodes graph-structured observations with node features, edge features, and edge connectivity. Sequence handles variable-length ordered collections from a base space. Text represents string-valued spaces with configurable character sets and length bounds. Tuple composes an ordered collection of heterogeneous sub-spaces. OneOf represents a choice among multiple mutually exclusive sub-spaces.

These composite spaces are essential for environments that cannot be naturally described by a single Box or Discrete space. They enable the design of environments with structured observations (such as molecular graphs, variable-length action lists, or natural language interfaces) while maintaining compatibility with the space API for sampling, containment checking, and serialization.

Usage

Use composite space types when defining environments whose observations or actions have inherent structure that cannot be flattened into a single array without losing semantic meaning. Graph spaces are appropriate for molecular, network, or relational domains. Sequence spaces suit tasks with variable-length outputs. MultiBinary and MultiDiscrete are useful for factored discrete action spaces. Tuple spaces compose heterogeneous data types. OneOf is useful when only one of several possible action types applies at each step. Text spaces suit environments with natural language interfaces.

Theoretical Basis

Composite spaces formalize the type system for structured RL interactions. Each space $𝒮$ defines:

Membership: $x \in 𝒮$ determines whether a sample is valid
Sampling: $x \sim 𝒮$ draws a random element according to a distribution
Shape: the structural description of elements

For MultiDiscrete with $n$ dimensions each having $k_{i}$ categories:

$𝒮 = {0, \dots, k_{1} - 1} \times {0, \dots, k_{2} - 1} \times \dots \times {0, \dots, k_{n} - 1}$

For Graph with node space $𝒩$ and edge space $ℰ$ :

Failed to parse (syntax error): {\displaystyle \mathcal{G} = \{ (V, E, \text{edge\_links}) \mid V \in \mathcal{N}^{n_v}, E \in \mathcal{E}^{n_e}, \text{edge\_links} \in \{0, \ldots, n_v - 1\}^{n_e \times 2} \}}

For Sequence with base space $ℬ$ :

$𝒮 = ⋃_{n = 0}^{\infty} ℬ^{n}$

# Composite space examples
multi_discrete = MultiDiscrete([5, 3, 2])   # 3 independent discrete variables
multi_binary = MultiBinary(8)                # 8-bit binary vector
graph = Graph(node_space=Box(0, 1, (4,)), edge_space=Discrete(3))
sequence = Sequence(Box(0, 1, (3,)))         # variable-length list of 3D vectors
text = Text(min_length=1, max_length=10)     # string of 1-10 characters
tuple_space = Tuple((Discrete(3), Box(0, 1, (2,))))
oneof = OneOf((Discrete(3), Box(0, 1, (2,))))

Composite spaces that are not numpy-flattenable (Graph, Sequence) set Failed to parse (syntax error): {\displaystyle \text{is\_np\_flattenable} = \text{False}} , signaling to utility functions that they cannot be converted to fixed-size arrays.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment