Spaces#

This module implements various spaces.

Spaces describe mathematical sets and are used in Gym to specify valid actions and observations. Every Gym environment must have the attributes action_space and observation_space. If, for instance, three possible actions (0,1,2) can be performed in your environment and observations are vectors in the two-dimensional unit cube, the environment code may contain the following two lines:

self.action_space = spaces.Discrete(3)
self.observation_space = spaces.Box(0, 1, shape=(2,))

All spaces inherit from the Space superclass.

The Base Class#

class gymnasium.spaces.Space(shape: Sequence[int] | None = None, dtype: npt.DTypeLike | None = None, seed: int | np.random.Generator | None = None)#

Superclass that is used to define observation and action spaces.

Spaces are crucially used in Gym to define the format of valid actions and observations. They serve various purposes:

  • They clearly define how to interact with environments, i.e. they specify what actions need to look like and what observations will look like

  • They allow us to work with highly structured data (e.g. in the form of elements of Dict spaces) and painlessly transform them into flat arrays that can be used in learning code

  • They provide a method to sample random elements. This is especially useful for exploration and debugging.

Different spaces can be combined hierarchically via container spaces (Tuple and Dict) to build a more expressive space

Warning

Custom observation & action spaces can inherit from the Space class. However, most use-cases should be covered by the existing space classes (e.g. Box, Discrete, etc…), and container classes (:class`Tuple` & Dict). Note that parametrized probability distributions (through the Space.sample() method), and batching functions (in gym.vector.VectorEnv), are only well-defined for instances of spaces provided in gym by default. Moreover, some implementations of Reinforcement Learning algorithms might not handle custom spaces properly. Use custom spaces with care.

Parameters:

  • shape (Optional[Sequence[int]]) – If elements of the space are numpy arrays, this should specify their shape.

  • dtype (Optional[Type | str]) – If elements of the space are numpy arrays, this should specify their dtype.

  • seed – Optionally, you can use this argument to seed the RNG that is used to sample from the space

Attributes#

property Space.shape: tuple[int, ...] | None#

Return the shape of the space as an immutable property.

property Space.dtype#

Return the data type of this space.

property Space.is_np_flattenable: bool#

Checks whether this space can be flattened to a gymnasium.spaces.Box.

Methods#

Each space implements the following functions:

gymnasium.spaces.space.Space.sample(self, mask: Any | None = None) → T_cov#

Randomly sample an element of this space.

Can be uniform or non-uniform sampling based on boundedness of space.

Parameters:

mask – A mask used for sampling, expected dtype=np.int8 and see sample implementation for expected shape.

Returns:

A sampled actions from the space

gymnasium.spaces.space.Space.contains(self, x: Any) → bool#

Return boolean specifying if x is a valid member of this space.

gymnasium.spaces.space.Space.seed(self, seed: int | None = None) → list[int]#

Seed the PRNG of this space and possibly the PRNGs of subspaces.

gymnasium.spaces.space.Space.to_jsonable(self, sample_n: Sequence[T_cov]) → list[Any]#

Convert a batch of samples from this space to a JSONable data type.

gymnasium.spaces.space.Space.from_jsonable(self, sample_n: list[Any]) → list[+T_cov]#

Convert a JSONable data type to a batch of samples from this space.

Fundamental Spaces#

Gymnasium has a number of fundamental spaces that are used as building boxes for more complex spaces.

  • Box - Supports continuous (and discrete) vectors or matrices, used for vector observations, images, etc

  • Discrete - Supports a single discrete number of values with an optional start for the values

  • MultiBinary - Supports single or matrices of binary values, used for holding down a button or if an agent has an object

  • MultiDiscrete - Supports multiple discrete values with multiple axes, used for controller actions

  • Text - Supports strings, used for passing agent messages, mission details, etc

Composite Spaces#

Often environment spaces require joining fundamental spaces together for vectorised environments, separate agents or readability of the space.

  • Dict - Supports a dictionary of keys and subspaces, used for a fixed number of unordered spaces

  • Tuple - Supports a tuple of subspaces, used for multiple for a fixed number of ordered spaces

  • Sequence - Supports a variable number of instances of a single subspace, used for entities spaces or selecting a variable number of actions

  • Graph - Supports graph based actions or observations with discrete or continuous nodes and edge values.

Utils#

Gymnasium contains a number of helpful utility functions for flattening and unflattening spaces. This can be important for passing information to neural networks.

  • utils.flatdim - The number of dimensions the flattened space will contain

  • utils.flatten_space - Flattens a space for which the flattened space instances will contain

  • utils.flatten - Flattens an instance of a space that is contained within the flattened version of the space

  • utils.unflatten - The reverse of the flatten_space function

Vector Utils#

When vectorizing environments, it is necessary to modify the observation and action spaces for new batched spaces sizes. Therefore, Gymnasium provides a number of additional functions used when using a space with a Vector environment.