Implementation:Farama Foundation Gymnasium MultiBinary 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 binary arrays of a fixed shape provided by Gymnasium.

Description

The MultiBinary space represents an n-dimensional binary array where each element is either 0 or 1. The shape of the array is fixed at construction time and can be a flat integer (producing a 1D array) or a sequence of integers (producing a multi-dimensional array). The dtype is always np.int8.

Sampling is performed by independent fair coin tosses -- each binary variable is independently set to 0 or 1 with equal probability. Sampling can be controlled via:

• A mask (np.int8 array) where 0 forces the output to 0, 1 forces the output to 1, and 2 allows random sampling.
• A probability (np.float64 array) where each element specifies the probability of the corresponding output being 1.

The space is numpy-flattenable (is_np_flattenable returns True), meaning it can be flattened to a 1D array via the flatten utility.

Usage

Use MultiBinary when the observation or action is a fixed-size collection of independent binary flags. Common examples include feature presence/absence indicators, multi-label classification outputs, or binary switch states.

Code Reference

Source Location

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

Signature

class MultiBinary(Space[NDArray[np.int8]]):
    def __init__(
        self,
        n: NDArray[np.integer[Any]] | Sequence[int] | int,
        seed: int | np.random.Generator | None = None,
    )

Import

from gymnasium.spaces import MultiBinary

I/O Contract

Inputs

Name	Type	Required	Description
n	int, Sequence[int], or NDArray[np.integer]	Yes	Defines the shape of the binary array. An integer produces a 1D array; a sequence produces a multi-dimensional array.
seed	int, np.random.Generator, or None	No	Optional seed for the random number generator.

Outputs

Name	Type	Description
sample() returns	NDArray[np.int8]	A binary array of the defined shape where each element is 0 or 1.
contains() returns	bool	Whether a given value is a valid binary array with the correct shape.

Key Methods

Method	Description
sample(mask=None, probability=None)	Generate a random binary array. Supports mask-based (deterministic 0/1 or random per element) and probability-based sampling.
contains(x)	Check that x is an ndarray of the correct shape containing only 0s and 1s.
to_jsonable(sample_n)	Convert a batch of samples to a JSON-serializable list.
from_jsonable(sample_n)	Convert JSON-serializable data back to a list of np.int8 arrays.

Usage Examples

from gymnasium.spaces import MultiBinary
import numpy as np

# 1D binary space with 5 elements
space = MultiBinary(5, seed=42)
sample = space.sample()
print(sample)        # e.g. array([1, 0, 1, 0, 1], dtype=int8)
print(sample.shape)  # (5,)

# Multi-dimensional binary space
space_2d = MultiBinary([3, 2], seed=42)
sample_2d = space_2d.sample()
print(sample_2d.shape)  # (3, 2)

# Masked sampling: force specific bits
mask = np.array([0, 1, 2, 0, 2], dtype=np.int8)
# 0 -> forced to 0, 1 -> forced to 1, 2 -> random
masked_sample = space.sample(mask=mask)
print(masked_sample[0])  # 0  (forced)
print(masked_sample[1])  # 1  (forced)

# Probability-based sampling
probs = np.array([0.9, 0.1, 0.5, 0.5, 0.8], dtype=np.float64)
prob_sample = space.sample(probability=probs)

# Membership check
print(np.array([0, 1, 1, 0, 0], dtype=np.int8) in space)  # True
print(np.array([0, 2, 1, 0, 0], dtype=np.int8) in space)  # False (2 is invalid)

Related Pages

• Environment:Farama_Foundation_Gymnasium_Python_3_10_Runtime
• Farama_Foundation_Gymnasium_Space_Base -- abstract base class for all spaces
• Farama_Foundation_Gymnasium_MultiDiscrete_Space -- similar multi-valued discrete space
• Farama_Foundation_Gymnasium_Space_Utils -- flatten/unflatten utilities