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 codeThey 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
andDict
) to build a more expressive spaceWarning
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 theSpace.sample()
method), and batching functions (ingym.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.Constructor of
Space
.- 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, etcDiscrete
- Supports a single discrete number of values with an optional start for the valuesMultiDiscrete
- Supports single or matrices of binary values, used for holding down a button or if an agent has an objectMultiBinary
- Supports multiple discrete values with multiple axes, used for controller actionsText
- 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 spacesTuple
- Supports a tuple of subspaces, used for multiple for a fixed number of ordered spacesSequence
- Supports a variable number of instances of a single subspace, used for entities spaces or selecting a variable number of actionsGraph
- 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 containutils.flatten_space
- Flattens a space for which the flattened space instances will containutils.flatten
- Flattens an instance of a space that is contained within the flattened version of the spaceutils.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.