Implementation:Farama Foundation Gymnasium OneOf 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 an exclusive union (direct sum) of multiple space types provided by Gymnasium.

Description

The OneOf space represents the direct sum of a collection of Space instances. Unlike a Tuple space (which represents the cartesian product where all sub-spaces are sampled simultaneously), a OneOf space samples from exactly one of its constituent sub-spaces at a time. Each sample is a 2-tuple of (subspace_index, subspace_sample), where subspace_index identifies which sub-space was selected and subspace_sample is a valid sample from that sub-space.

The sub-space is selected uniformly at random during sampling. The space is numpy-flattenable if and only if all constituent sub-spaces are flattenable.

When flattened via the flatten utility, the result is a 1D array where the first element is the sub-space index and the remaining elements are the flattened sample, padded to the maximum flat dimension across all sub-spaces.

Usage

Use OneOf when the action or observation can come from one of several distinct types of spaces that are mutually exclusive. For example, an agent that can either move continuously (Box) or perform a discrete special action (Discrete), but not both simultaneously.

Code Reference

Source Location

Repository: Farama_Foundation_Gymnasium
File: gymnasium/spaces/oneof.py

Signature

class OneOf(Space[Any]):
    def __init__(
        self,
        spaces: Iterable[Space[Any]],
        seed: int | typing.Sequence[int] | np.random.Generator | None = None,
    )

Import

from gymnasium.spaces import OneOf

I/O Contract

Inputs

Name	Type	Required	Description
spaces	`Iterable[Space]`	Yes	The collection of sub-spaces. Must be non-empty. Each element must be a `Space` instance.
seed	`int`, `Sequence[int]`, `np.random.Generator`, or `None`	No	Optional seed for the random number generator. Tuple seeds should have length `len(spaces) + 1`.

Outputs

Name	Type	Description
sample() returns	`tuple[int, Any]`	A 2-tuple of `(subspace_index, subspace_sample)` where the index identifies which sub-space was sampled.
contains() returns	`bool`	Whether a given 2-tuple has a valid index and the sample is contained in the corresponding sub-space.

Key Methods

Method	Description
`sample(mask=None, probability=None)`	Randomly select one sub-space (uniformly) and sample from it. Mask or probability tuples must match the number of sub-spaces.
`contains(x)`	Check that `x` is a 2-tuple with a valid integer index and the second element is contained in the corresponding sub-space.
`seed(seed)`	Seed the PRNG. Accepts `None`, `int`, or a tuple of ints (length = `len(spaces) + 1`).
`__getitem__(index)`	Access a sub-space by index.
`__len__()`	Returns the number of sub-spaces.
`to_jsonable(sample_n)`	Convert a batch of samples to JSON-serializable format.
`from_jsonable(sample_n)`	Convert JSON-serializable data back to samples.

Usage Examples

from gymnasium.spaces import OneOf, Box, Discrete
import numpy as np

# An agent can either move continuously OR perform a discrete action
space = OneOf((Discrete(3), Box(-1, 1, shape=(2,))), seed=123)

# Sampling returns (index, sample)
sample = space.sample()
print(sample)
# e.g. (np.int64(0), np.int64(2))   -- sampled from Discrete(3)
# or   (np.int64(1), array([0.5, -0.3], dtype=float32)) -- sampled from Box

# Access sub-spaces
print(space[0])     # Discrete(3)
print(space[1])     # Box(-1.0, 1.0, (2,), float32)
print(len(space))   # 2

# Membership check
print((np.int64(0), np.int64(1)) in space)                    # True
print((np.int64(1), np.array([0.5, 0.3], dtype=np.float32)) in space)  # True
print((np.int64(2), np.int64(0)) in space)                    # False (index 2 out of range)

# Masked sampling
mask = (
    np.array([1, 0, 1], dtype=np.int8),  # mask for Discrete(3)
    None,                                  # no mask for Box
)
masked_sample = space.sample(mask=mask)

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 -- cartesian product (all sub-spaces sampled together)
Farama_Foundation_Gymnasium_Space_Utils -- flatten/unflatten with OneOf-specific padding logic

Page Connections

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

Principle

Implementation

Heuristic

Environment