Implementation:Farama Foundation Gymnasium Sequence Space

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

Overview

Concrete tool for representing variable-length sequences of elements from a given feature space provided by Gymnasium.

Description

The Sequence space represents the set of all finite-length tuples (a_0, ..., a_n) where each element a_i belongs to a specified feature space and the length n is not fixed. During sampling, the length is drawn from a geometric distribution with parameter p=0.25 by default (yielding an expected length of 4).

The space supports two modes via the stack parameter:

• stack=False (default): Samples are returned as Python tuples of individual feature space samples.
• stack=True: Samples are stacked into a single array using gymnasium.vector.utils.concatenate, producing a batched array rather than a tuple. This mode also changes how contains, to_jsonable, and from_jsonable operate.

The Sequence space is not numpy-flattenable (is_np_flattenable returns False) because of its variable length. It cannot be converted to a single Box space.

Usage

Use Sequence when the observation or action has a variable number of elements from the same space. Common examples include variable-length text token sequences, trajectories of varying length, or sets of detected objects where the count changes per time step.

Code Reference

Source Location

• Repository: Farama_Foundation_Gymnasium
• File: gymnasium/spaces/sequence.py

Signature

class Sequence(Space[tuple[Any, ...] | Any]):
    def __init__(
        self,
        space: Space[Any],
        seed: int | np.random.Generator | None = None,
        stack: bool = False,
    )

Import

from gymnasium.spaces import Sequence

I/O Contract

Inputs

Name	Type	Required	Description
space	Space	Yes	The feature space that each element of the sequence must belong to.
seed	int, np.random.Generator, or None	No	Optional seed for the random number generator.
stack	bool	No	If True, samples are stacked into a single array. Defaults to False.

Outputs

Name	Type	Description
sample() returns (stack=False)	tuple[Any, ...]	A tuple of random length containing samples from the feature space.
sample() returns (stack=True)	Stacked array type	A batched array produced by stacking individual feature space samples.
contains() returns	bool	Whether a given value is a valid sequence of elements from the feature space.

Key Methods

Method	Description
sample(mask=None, probability=None)	Generate a random sequence. The mask or probability is a 2-tuple of (length_spec, feature_mask). The length_spec can be None (geometric distribution), an int (fixed length), or an NDArray of integers (length drawn from the array).
contains(x)	For stack=False, checks that x is a tuple and all elements are in the feature space. For stack=True, iterates over the stacked array.
seed(seed)	Seed the Sequence and feature space PRNGs. Accepts None, int, or a 2-tuple of ints.
generate_sample_length(length_mask, mask_type)	Determine the length of the sequence to sample, given a length mask.
to_jsonable(sample_n)	Convert a batch of samples to JSON-serializable format.
from_jsonable(sample_n)	Convert JSON-serializable data back to sequence samples.

Usage Examples

from gymnasium.spaces import Sequence, Box, Discrete

# Variable-length sequence of 1D continuous values
space = Sequence(Box(0, 1, shape=(1,)), seed=0)
sample = space.sample()
print(type(sample))   # <class 'tuple'>
print(len(sample))    # random length, e.g. 3

# Fixed-length sampling via mask
fixed_sample = space.sample(mask=(5, None))  # exactly 5 elements
print(len(fixed_sample))  # 5

# Stacked mode
stacked_space = Sequence(Box(0, 1, shape=(1,)), stack=True, seed=0)
stacked_sample = stacked_space.sample()
print(type(stacked_sample))  # <class 'numpy.ndarray'>
print(stacked_sample.shape)  # e.g. (3, 1)

# Sequence of discrete values
disc_seq = Sequence(Discrete(4), seed=42)
disc_sample = disc_seq.sample()
print(disc_sample)  # e.g. (2, 0, 3, 1)

# Membership check
print((Box(0, 1, shape=(1,)).sample(),) * 3 in space)  # True (if values valid)

Related Pages

• Environment:Farama_Foundation_Gymnasium_Python_3_10_Runtime
• Farama_Foundation_Gymnasium_Space_Base -- abstract base class for all spaces
• Farama_Foundation_Gymnasium_Tuple_Space -- fixed-length composite space (cartesian product)
• Farama_Foundation_Gymnasium_Space_Utils -- flatten/unflatten utilities with Sequence-specific dispatches