Fundamental Spaces#

Box#

A (possibly unbounded) box in \(\mathbb{R}^n\).

Specifically, a Box represents the Cartesian product of n closed intervals. Each interval has the form of one of \([a, b]\), \((-\infty, b]\), \([a, \infty)\), or \((-\infty, \infty)\).

There are two common use cases:

Identical bound for each dimension:

>>> Box(low=-1.0, high=2.0, shape=(3, 4), dtype=np.float32)
Box(-1.0, 2.0, (3, 4), float32)

Independent bound for each dimension:

>>> Box(low=np.array([-1.0, -2.0]), high=np.array([2.0, 4.0]), dtype=np.float32)
Box([-1. -2.], [2. 4.], (2,), float32)

Constructor of Box.

The argument low specifies the lower bound of each dimension and high specifies the upper bounds. I.e., the space that is constructed will be the product of the intervals \([\text{low}[i], \text{high}[i]]\).

If low (or high) is a scalar, the lower bound (or upper bound, respectively) will be assumed to be this value across all dimensions.

Parameters:

low (Union[SupportsFloat, np.ndarray]) – Lower bounds of the intervals.
high (Union[SupportsFloat, np.ndarray]) – Upper bounds of the intervals.
shape (Optional[Sequence[int]]) – The shape is inferred from the shape of low or high np.ndarray`s with `low and high scalars defaulting to a shape of (1,)
dtype – The dtype of the elements of the space. If this is an integer type, the Box is essentially a discrete space.
seed – Optionally, you can use this argument to seed the RNG that is used to sample from the space.

Raises:

ValueError – If no shape information is provided (shape is None, low is None and high is None) then a value error is raised.

Box.sample(mask: None = None) → ndarray[Any, dtype[Any]]#

Generates a single random sample inside the Box.

In creating a sample of the box, each coordinate is sampled (independently) from a distribution that is chosen according to the form of the interval:

\([a, b]\) : uniform distribution
\([a, \infty)\) : shifted exponential distribution
\((-\infty, b]\) : shifted negative exponential distribution
\((-\infty, \infty)\) : normal distribution

Parameters:: mask – A mask for sampling values from the Box space, currently unsupported.
Returns:: A sampled value from the Box

Box.seed(seed: int | None = None) → list[int]#: Seed the PRNG of this space and possibly the PRNGs of subspaces.

Box.is_bounded(manner: str = 'both') → bool#

Checks whether the box is bounded in some sense.

Parameters:: manner (str) – One of "both", "below", "above".
Returns:: If the space is bounded
Raises:: ValueError – If manner is neither "both" nor "below" or "above"

Discrete#

class gymnasium.spaces.Discrete(n: int | np.integer[Any], seed: int | np.random.Generator | None = None, start: int | np.integer[Any] = 0)#

A space consisting of finitely many elements.

This class represents a finite subset of integers, more specifically a set of the form \(\{ a, a+1, \dots, a+n-1 \}\).

Example:

>>> Discrete(2)            # {0, 1}
Discrete(2)
>>> Discrete(3, start=-1)  # {-1, 0, 1}
Discrete(3, start=-1)

Constructor of Discrete space.

This will construct the space \(\{\text{start}, ..., \text{start} + n - 1\}\).

Parameters:

n (int) – The number of elements of this space.
seed – Optionally, you can use this argument to seed the RNG that is used to sample from the Dict space.
start (int) – The smallest element of this space.

Discrete.sample(mask: MaskNDArray | None = None) → int#

Generates a single random sample from this space.

A sample will be chosen uniformly at random with the mask if provided

Parameters:: mask – An optional mask for if an action can be selected. Expected np.ndarray of shape (n,) and dtype np.int8 where 1 represents valid actions and 0 invalid / infeasible actions. If there are no possible actions (i.e. np.all(mask == 0)) then space.start will be returned.
Returns:: A sampled integer from the space

Discrete.seed(seed: int | None = None) → list[int]#: Seed the PRNG of this space and possibly the PRNGs of subspaces.

MultiBinary#

class gymnasium.spaces.MultiBinary(n: npt.NDArray[np.integer[Any]] | Sequence[int] | int, seed: int | np.random.Generator | None = None)#

An n-shape binary space.

Elements of this space are binary arrays of a shape that is fixed during construction.

Example Usage:

>>> observation_space = MultiBinary(5, seed=42)
>>> observation_space.sample()
array([1, 0, 1, 0, 1], dtype=int8)
>>> observation_space = MultiBinary([3, 2], seed=42)
>>> observation_space.sample()
array([[1, 0],
       [1, 0],
       [1, 1]], dtype=int8)

Constructor of MultiBinary space.

Parameters:

n – This will fix the shape of elements of the space. It can either be an integer (if the space is flat) or some sort of sequence (tuple, list or np.ndarray) if there are multiple axes.
seed – Optionally, you can use this argument to seed the RNG that is used to sample from the space.

MultiBinary.sample(mask: MaskNDArray | None = None) → npt.NDArray[np.int8]#

Generates a single random sample from this space.

A sample is drawn by independent, fair coin tosses (one toss per binary variable of the space).

Parameters:: mask – An optional np.ndarray to mask samples with expected shape of space.shape. For mask == 0 then the samples will be 0 and mask == 1 then random samples will be generated. The expected mask shape is the space shape and mask dtype is np.int8.
Returns:: Sampled values from space

MultiBinary.seed(seed: int | None = None) → list[int]#: Seed the PRNG of this space and possibly the PRNGs of subspaces.

MultiDiscrete#

class gymnasium.spaces.MultiDiscrete(nvec: npt.NDArray[np.integer[Any]] | list[int], dtype: str | type[np.integer[Any]] = np.int64, seed: int | np.random.Generator | None = None)#

This represents the cartesian product of arbitrary Discrete spaces.

It is useful to represent game controllers or keyboards where each key can be represented as a discrete action space.

Note

Some environment wrappers assume a value of 0 always represents the NOOP action.

e.g. Nintendo Game Controller - Can be conceptualized as 3 discrete action spaces:

Arrow Keys: Discrete 5 - NOOP[0], UP[1], RIGHT[2], DOWN[3], LEFT[4] - params: min: 0, max: 4
Button A: Discrete 2 - NOOP[0], Pressed[1] - params: min: 0, max: 1
Button B: Discrete 2 - NOOP[0], Pressed[1] - params: min: 0, max: 1

It can be initialized as MultiDiscrete([ 5, 2, 2 ]) such that a sample might be array([3, 1, 0]).

Although this feature is rarely used, MultiDiscrete spaces may also have several axes if nvec has several axes:

Example:

>> d = MultiDiscrete(np.array([[1, 2], [3, 4]]), seed=42)
>> d.sample()
array([[0, 0],
       [2, 3]])

Constructor of MultiDiscrete space.

The argument nvec will determine the number of values each categorical variable can take.

Parameters:

nvec – vector of counts of each categorical variable. This will usually be a list of integers. However, you may also pass a more complicated numpy array if you’d like the space to have several axes.
dtype – This should be some kind of integer type.
seed – Optionally, you can use this argument to seed the RNG that is used to sample from the space.

MultiDiscrete.sample(mask: tuple[MaskNDArray, ...] | None = None) → npt.NDArray[np.integer[Any]]#

Generates a single random sample this space.

Parameters:: mask – An optional mask for multi-discrete, expects tuples with a np.ndarray mask in the position of each action with shape (n,) where n is the number of actions and dtype=np.int8. Only mask values == 1 are possible to sample unless all mask values for an action are 0 then the default action 0 is sampled.
Returns:: An `np.ndarray` of shape `space.shape`

MultiDiscrete.seed(seed: int | None = None) → list[int]#: Seed the PRNG of this space and possibly the PRNGs of subspaces.

Text#

class gymnasium.spaces.Text(max_length: int, *, min_length: int = 1, charset: set[str] | str = alphanumeric, seed: int | np.random.Generator | None = None)#

A space representing a string comprised of characters from a given charset.

Example::

>>> # {"", "B5", "hello", ...}
>>> Text(5)
Text(1, 5, characters=0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz)
>>> # {"0", "42", "0123456789", ...}
>>> import string
>>> Text(min_length = 1,
...      max_length = 10,
...      charset = string.digits)
Text(1, 10, characters=0123456789)

Constructor of Text space.

Both bounds for text length are inclusive.

Parameters:

min_length (int) – Minimum text length (in characters). Defaults to 1 to prevent empty strings.
max_length (int) – Maximum text length (in characters).
charset (Union[set], str) – Character set, defaults to the lower and upper english alphabet plus latin digits.
seed – The seed for sampling from the space.

Text.sample(mask: None | tuple[int | None, npt.NDArray[np.int8] | None] = None) → str#

Generates a single random sample from this space with by default a random length between min_length and max_length and sampled from the charset.

Parameters:: mask – An optional tuples of length and mask for the text. The length is expected to be between the min_length and max_length otherwise a random integer between min_length and max_length is selected. For the mask, we expect a numpy array of length of the charset passed with dtype == np.int8. If the charlist mask is all zero then an empty string is returned no matter the min_length
Returns:: A sampled string from the space

Text.seed(seed: int | None = None) → list[int]#: Seed the PRNG of this space and possibly the PRNGs of subspaces.