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
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
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
Dictspaces) 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.
Custom observation & action spaces can inherit from the
Spaceclass. However, most use-cases should be covered by the existing space classes (e.g.
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.
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
- 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.
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.
mask – A mask used for sampling, expected
dtype=np.int8and see sample implementation for expected shape.
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.
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
MultiDiscrete- Supports single or matrices of binary values, used for holding down a button or if an agent has an object
MultiBinary- Supports multiple discrete values with multiple axes, used for controller actions
Text- Supports strings, used for passing agent messages, mission details, etc
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.
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
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.