Implementation:Farama Foundation Gymnasium Discrete Space

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

Overview

Concrete tool for defining finite integer action/observation spaces provided by the Gymnasium library.

Description

The Discrete class represents a space of finitely many integers. It supports uniform random sampling, action mask sampling (binary mask for valid/invalid actions), and probability-weighted sampling. The n property gives the number of actions, commonly used for Q-table initialization (e.g., np.zeros(env.action_space.n)).

Usage

Use this class to define environments with finite action sets. Access env.action_space.n to determine the number of valid actions for initializing Q-tables, policy networks, or epsilon-greedy strategies.

Code Reference

Source Location

• Repository: Gymnasium
• File: gymnasium/spaces/discrete.py
• Lines: L15-217

Signature

class Discrete(Space[IntType]):
    def __init__(
        self,
        n: int | np.integer[Any],
        seed: int | np.random.Generator | None = None,
        start: int | np.integer[Any] = 0,
        dtype: str | type[np.integer[Any]] = np.int64,
    ):
        """Constructor of Discrete space.

        Constructs the space {start, ..., start + n - 1}.

        Args:
            n: The number of elements of this space.
            seed: Optionally seed the RNG for sampling.
            start: The smallest element of this space.
            dtype: The data type (e.g., np.int64, np.int32).
        """

    def sample(
        self,
        mask: MaskNDArray | None = None,
        probability: MaskNDArray | None = None,
    ) -> IntType:
        """Generates a single random sample.

        Args:
            mask: Binary mask array of shape (n,) with dtype np.int8.
            probability: Probability array of shape (n,) with dtype np.float64.

        Returns:
            A sampled integer from the space.
        """

Import

from gymnasium.spaces import Discrete

I/O Contract

Inputs

Name	Type	Required	Description
n	int	Yes	Number of elements in the space
seed	int or Generator or None	No	Random seed for sampling
start	int	No	Smallest element (default 0)
dtype	type	No	Integer dtype (default np.int64)

Outputs

Name	Type	Description
sample()	IntType	A random integer from {start, ..., start+n-1}
n	np.integer	Number of elements in the space
contains(x)	bool	Whether x is a valid member

Usage Examples

Q-Table Initialization

import gymnasium as gym
import numpy as np
from collections import defaultdict

env = gym.make("Blackjack-v1")

# Access discrete action space size
n_actions = env.action_space.n  # 2 (hit or stand)

# Initialize Q-table using action space size
q_table = defaultdict(lambda: np.zeros(n_actions))

Action Masking

from gymnasium.spaces import Discrete
import numpy as np

space = Discrete(4)  # {0, 1, 2, 3}

# Sample with mask (only actions 1 and 3 are valid)
mask = np.array([0, 1, 0, 1], dtype=np.int8)
action = space.sample(mask=mask)  # Returns 1 or 3

Related Pages

Implements Principle

• Principle:Farama_Foundation_Gymnasium_Discrete_Action_Space

Requires Environment

• Environment:Farama_Foundation_Gymnasium_Python_3_10_Runtime