# Spaces Utils#

gymnasium.spaces.utils.flatten_space(space: Space[Any]) [source]#
gymnasium.spaces.utils.flatten_space(space: Box) Box
gymnasium.spaces.utils.flatten_space(space: ) Box
gymnasium.spaces.utils.flatten_space(space: ) Box
gymnasium.spaces.utils.flatten_space(space: ) Box
gymnasium.spaces.utils.flatten_space(space: Tuple)
gymnasium.spaces.utils.flatten_space(space: Dict)
gymnasium.spaces.utils.flatten_space(space: Graph)
gymnasium.spaces.utils.flatten_space(space: Text) Box
gymnasium.spaces.utils.flatten_space(space: Sequence)

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

This function will attempt to flatten `space` into a single `gymnasium.spaces.Box` space. However, this might not be possible when `space` is an instance of `gymnasium.spaces.Graph`, `gymnasium.spaces.Sequence` or a compound space that contains a `gymnasium.spaces.Graph` or `gymnasium.spaces.Sequence` space. This is equivalent to `flatten()`, but operates on the space itself. The result for non-graph spaces is always a `gymnasium.spaces.Box` with flat boundaries. While the result for graph spaces is always a `gymnasium.spaces.Graph` with `Graph.node_space` being a `Box` with flat boundaries and `Graph.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 flattened space. However, sampling from the flattened space is not necessarily reversible. For example, sampling from a flattened Discrete space is the same as sampling from a Box, and the results may not be integers or one-hot encodings. This may result in errors or non-uniform sampling.

Parameters:

space – The space to flatten

Returns:

A flattened Box

Raises:

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

Example

Flatten spaces.Box: >>> from gymnasium.spaces import Box >>> box = Box(0.0, 1.0, shape=(3, 4, 5)) >>> box Box(0.0, 1.0, (3, 4, 5), float32) >>> flatten_space(box) Box(0.0, 1.0, (60,), float32) >>> flatten(box, box.sample()) in flatten_space(box) True

Flatten spaces.Discrete: >>> from gymnasium.spaces import Discrete >>> discrete = Discrete(5) >>> flatten_space(discrete) Box(0, 1, (5,), int64) >>> flatten(discrete, discrete.sample()) in flatten_space(discrete) True

Flatten spaces.Dict: >>> from gymnasium.spaces import Dict, Discrete, Box >>> space = Dict({“position”: Discrete(2), “velocity”: Box(0, 1, shape=(2, 2))}) >>> flatten_space(space) Box(0.0, 1.0, (6,), float64) >>> flatten(space, space.sample()) in flatten_space(space) True

Flatten spaces.Graph: >>> from gymnasium.spaces import Graph, Discrete, Box >>> 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

gymnasium.spaces.utils.flatten(space: Space[T], x: T) ndarray[Any, dtype[Any]] | Dict[str, Any] | Tuple[Any, ...] | GraphInstance[source]#
gymnasium.spaces.utils.flatten(space: , x: NDArray[Any]) NDArray[Any]
gymnasium.spaces.utils.flatten(space: , x: NDArray[Any]) NDArray[Any]
gymnasium.spaces.utils.flatten(space: Discrete, x: int64) ndarray[Any, dtype[int64]]
gymnasium.spaces.utils.flatten(space: MultiDiscrete, x: ndarray[Any, dtype[int64]]) ndarray[Any, dtype[int64]]
gymnasium.spaces.utils.flatten(space: Tuple, x: tuple[Any, ...]) tuple[Any, ...] | NDArray[Any]
gymnasium.spaces.utils.flatten(space: Dict, x: dict[str, Any]) dict[str, Any] | NDArray[Any]
gymnasium.spaces.utils.flatten(space: Graph, x: GraphInstance) GraphInstance
gymnasium.spaces.utils.flatten(space: Text, x: str) ndarray[Any, dtype[int32]]
gymnasium.spaces.utils.flatten(space: Sequence, x: tuple[Any, ...] | Any) tuple[Any, ...] | Any

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:

The flattened datapoint

Raises:

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

Example

```>>> from gymnasium.spaces import Box, Discrete, Tuple
>>> space = Box(0, 1, shape=(3, 5))
>>> flatten(space, space.sample()).shape
(15,)
>>> space = Discrete(4)
>>> flatten(space, 2)
array([0, 0, 1, 0])
>>> space = Tuple((Box(0, 1, shape=(2,)), Box(0, 1, shape=(3,)), Discrete(3)))
>>> example = ((.5, .25), (1., 0., .2), 1)
>>> flatten(space, example)
array([0.5 , 0.25, 1.  , 0.  , 0.2 , 0.  , 1.  , 0.  ])
```
gymnasium.spaces.utils.flatdim(space: Space[Any]) int[source]#
gymnasium.spaces.utils.flatdim(space: ) int
gymnasium.spaces.utils.flatdim(space: ) 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.

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 `gymnasium.spaces.Box`

Example

```>>> from gymnasium.spaces import Dict, Discrete
>>> space = Dict({"position": Discrete(2), "velocity": Discrete(3)})
>>> flatdim(space)
5
```
gymnasium.spaces.utils.unflatten(space: Space[T], x: ndarray[Any, dtype[Any]] | Dict[str, Any] | Tuple[Any, ...] | GraphInstance) T[source]#
gymnasium.spaces.utils.unflatten(space: , x: NDArray[Any]) NDArray[Any]
gymnasium.spaces.utils.unflatten(space: , x: NDArray[Any]) NDArray[Any]
gymnasium.spaces.utils.unflatten(space: Discrete, x: ndarray[Any, dtype[int64]]) int64
gymnasium.spaces.utils.unflatten(space: MultiDiscrete, x: ndarray[Any, dtype[integer[Any]]]) ndarray[Any, dtype[integer[Any]]]
gymnasium.spaces.utils.unflatten(space: Tuple, x: NDArray[Any] | tuple[Any, ...]) tuple[Any, ...]
gymnasium.spaces.utils.unflatten(space: Dict, x: NDArray[Any] | dict[str, Any]) dict[str, Any]
gymnasium.spaces.utils.unflatten(space: Graph, x: GraphInstance) GraphInstance
gymnasium.spaces.utils.unflatten(space: Text, x: ndarray[Any, dtype[int32]]) str
gymnasium.spaces.utils.unflatten(space: Sequence, x: tuple[Any, ...]) tuple[Any, ...] | Any

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