Spaces Utils#

gymnasium.spaces.utils.flatdim(space: Space) → int#

gymnasium.spaces.utils.flatdim(space: Union[Box, MultiBinary]) → int

gymnasium.spaces.utils.flatdim(space: Discrete) → int

gymnasium.spaces.utils.flatdim(space: MultiDiscrete) → int

gymnasium.spaces.utils.flatdim(space: Tuple) → int

gymnasium.spaces.utils.flatdim(space: Dict) → int

gymnasium.spaces.utils.flatdim(space: Graph)

gymnasium.spaces.utils.flatdim(space: Text) → int

Return the number of dimensions a flattened equivalent of this space would have.

Example usage:

>>> from gymnasium.spaces import Discrete
>>> space = Dict({"position": Discrete(2), "velocity": Discrete(3)})
>>> flatdim(space)
5

Parameters:

space – The space to return the number of dimensions of the flattened spaces

Returns:

The number of dimensions for the flattened spaces

Raises:

NotImplementedError – if the space is not defined in gym.spaces.
ValueError – if the space cannot be flattened into a Box

gymnasium.spaces.utils.flatten_space(space: Space) → Union[Dict, Sequence, Tuple, Graph]#

gymnasium.spaces.utils.flatten_space(space: Box) → Box

gymnasium.spaces.utils.flatten_space(space: Union[Discrete, MultiBinary, MultiDiscrete]) → Box

gymnasium.spaces.utils.flatten_space(space: Tuple) → Union[Box, Tuple]

gymnasium.spaces.utils.flatten_space(space: Dict) → Union[Box, Dict]

gymnasium.spaces.utils.flatten_space(space: Graph) → Graph

gymnasium.spaces.utils.flatten_space(space: Text) → Box

gymnasium.spaces.utils.flatten_space(space: Sequence) → Sequence

Flatten a space into a space that is as flat as possible.

This function will attempt to flatten space into a single Box space. However, this might not be possible when space is an instance of Graph, Sequence or a compound space that contains a Graph or Sequence`space. This is equivalent to :func:`flatten, but operates on the space itself. The result for non-graph spaces is always a Box with flat boundaries. While the result for graph spaces is always a Graph with node_space being a Box with flat boundaries and edge_space being a Box with flat boundaries or None. The box has exactly flatdim() dimensions. Flattening a sample of the original space has the same effect as taking a sample of the flattenend space.

Example:

>>> box = Box(0.0, 1.0, shape=(3, 4, 5))
>>> box
Box(3, 4, 5)
>>> flatten_space(box)
Box(60,)
>>> flatten(box, box.sample()) in flatten_space(box)
True

Example that flattens a discrete space:

>>> discrete = Discrete(5)
>>> flatten_space(discrete)
Box(5,)
>>> flatten(box, box.sample()) in flatten_space(box)
True

Example that recursively flattens a dict:

>>> space = Dict({"position": Discrete(2), "velocity": Box(0, 1, shape=(2, 2))})
>>> flatten_space(space)
Box(6,)
>>> flatten(space, space.sample()) in flatten_space(space)
True

Example that flattens a graph:

>>> space = Graph(node_space=Box(low=-100, high=100, shape=(3, 4)), edge_space=Discrete(5))
>>> flatten_space(space)
Graph(Box(-100.0, 100.0, (12,), float32), Box(0, 1, (5,), int64))
>>> flatten(space, space.sample()) in flatten_space(space)
True

Parameters:: space – The space to flatten
Returns:: A flattened Box
Raises:: NotImplementedError – if the space is not defined in gymnasium.spaces.

gymnasium.spaces.utils.flatten(space: Space[T], x: T) → Union[ndarray, Dict, tuple, GraphInstance]#

gymnasium.spaces.utils.flatten(space: MultiBinary, x) → ndarray

gymnasium.spaces.utils.flatten(space: Box, x) → ndarray

gymnasium.spaces.utils.flatten(space: Discrete, x) → ndarray

gymnasium.spaces.utils.flatten(space: MultiDiscrete, x) → ndarray

gymnasium.spaces.utils.flatten(space: Tuple, x) → Union[tuple, ndarray]

gymnasium.spaces.utils.flatten(space: Dict, x) → Union[dict, ndarray]

gymnasium.spaces.utils.flatten(space: Graph, x) → GraphInstance

gymnasium.spaces.utils.flatten(space: Text, x: str) → ndarray

gymnasium.spaces.utils.flatten(space: Sequence, x) → tuple

Flatten a data point from a space.

This is useful when e.g. points from spaces must be passed to a neural network, which only understands flat arrays of floats.

Parameters:

space – The space that x is flattened by
x – The value to flatten

Returns:

- For ``Box`` and ``MultiBinary``, this is a flattened array
- For ``Discrete`` and ``MultiDiscrete``, this is a flattened one-hot array of the sample
- For ``Tuple`` and ``Dict``, this is a concatenated array the subspaces (does not support graph subspaces)
- For graph spaces, returns `GraphInstance` where –
- nodes are n x k arrays
- edges are either:
  - m x k arrays
  - None
- edge_links are either:
  - m x 2 arrays
  - None

Raises:

NotImplementedError – If the space is not defined in gymnasium.spaces.

gymnasium.spaces.utils.unflatten(space: Space[T], x: Union[ndarray, Dict, tuple, GraphInstance]) → T#

gymnasium.spaces.utils.unflatten(space: Union[Box, MultiBinary], x: ndarray) → ndarray

gymnasium.spaces.utils.unflatten(space: Discrete, x: ndarray) → int

gymnasium.spaces.utils.unflatten(space: MultiDiscrete, x: ndarray) → ndarray

gymnasium.spaces.utils.unflatten(space: Tuple, x: Union[ndarray, tuple]) → tuple

gymnasium.spaces.utils.unflatten(space: Dict, x: Union[ndarray, Dict]) → dict

gymnasium.spaces.utils.unflatten(space: Graph, x: GraphInstance) → GraphInstance

gymnasium.spaces.utils.unflatten(space: Text, x: ndarray) → str

gymnasium.spaces.utils.unflatten(space: Sequence, x: tuple) → tuple

Unflatten a data point from a space.

This reverses the transformation applied by flatten(). You must ensure that the space argument is the same as for the flatten() call.

Parameters:

space – The space used to unflatten x
x – The array to unflatten

Returns:

A point with a structure that matches the space.

Raises:

NotImplementedError – if the space is not defined in gymnasium.spaces.