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.

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

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 (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.

property Space.np_random: Generator

Lazily seed the PRNG since this is expensive and only needed if sampling from this space.

As seed() is not guaranteed to set the _np_random for particular seeds. We add a check after seed() to set a new random number generator.

Methods

Each space implements the following functions:

Space.sample(mask: Any | None = None) → T_cov[source]

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

Space.contains(x: Any) → bool[source]

Return boolean specifying if x is a valid member of this space, equivalent to sample in space.

Space.seed(seed: int | None = None) → int | list[int] | dict[str, int][source]

Seed the pseudorandom number generator (PRNG) of this space and, if applicable, the PRNGs of subspaces.

Parameters:

seed – The seed value for the space. This is expanded for composite spaces to accept multiple values. For further details, please refer to the space’s documentation.

Returns:

The seed values used for all the PRNGs, for composite spaces this can be a tuple or dictionary of values.

Space.to_jsonable(sample_n: Sequence[T_cov]) → list[Any][source]

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

Space.from_jsonable(sample_n: list[Any]) → list[T_cov][source]

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

  • OneOf - Supports optional action spaces such that an action can be one of N possible subspaces

Utility functions

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

Vector Utility functions

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.