Spaces Utils

gymnasium.spaces.utils.flatten_space(space: ¶

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: 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: Box

gymnasium.spaces.utils.flatten_space(space: Sequence

gymnasium.spaces.utils.flatten_space(space: Box

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

This function will attempt to flatten space into a single 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

Example - 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

Example - 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

Example - 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: ¶

gymnasium.spaces.utils.flatten(space: MultiBinary, x: ndarray[tuple[int, ...], dtype[Any]]) → ndarray[tuple[int, ...], dtype[Any]]

gymnasium.spaces.utils.flatten(space: MultiBinary, x: ndarray[tuple[int, ...], dtype[Any]]) → ndarray[tuple[int, ...], dtype[Any]]

gymnasium.spaces.utils.flatten(space: Discrete, x: int64) → ndarray[tuple[int, ...], dtype[int64]]

gymnasium.spaces.utils.flatten(space: MultiDiscrete, x: ndarray[tuple[int, ...], dtype[int64]]) → ndarray[tuple[int, ...], dtype[int64]]

gymnasium.spaces.utils.flatten(space: Tuple, x: tuple[Any, ...]) → tuple[Any, ...] | ndarray[tuple[int, ...], dtype[Any]]

gymnasium.spaces.utils.flatten(space: Dict, x: dict[str, Any]) → dict[str, Any] | ndarray[tuple[int, ...], dtype[Any]]

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

gymnasium.spaces.utils.flatten(space: Text, x: str) → ndarray[tuple[int, ...], dtype[int32]]

gymnasium.spaces.utils.flatten(space: Sequence, x: tuple[Any, ...] | Any) → tuple[Any, ...] | Any

gymnasium.spaces.utils.flatten(space: OneOf, x: tuple[int, Any]) → ndarray[tuple[int, ...], dtype[Any]]

Flatten a data point from a space.

This is useful when e.g. points from spaces must be ed 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 –

• For gymnasium.spaces.MultiBinary, this is a flattened array

• For gymnasium.spaces.MultiDiscrete, this is a flattened one-hot array of the sample

• For gymnasium.spaces.Dict, this is a concatenated array the subspaces (does not graph subspaces)

• For graph spaces, returns GraphInstance where:

  • GraphInstance.nodes are n x k arrays

  • GraphInstance.edges are either:

    • m x k arrays

    • None

  • GraphInstance.edge_links are either:

    • m x 2 arrays

    • None

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: ¶

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

gymnasium.spaces.utils.flatdim(space: 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

gymnasium.spaces.utils.flatdim(space: OneOf) → 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: ¶

gymnasium.spaces.utils.unflatten(space: MultiBinary, x: ndarray[tuple[int, ...], dtype[Any]]) → ndarray[tuple[int, ...], dtype[Any]]

gymnasium.spaces.utils.unflatten(space: MultiBinary, x: ndarray[tuple[int, ...], dtype[Any]]) → ndarray[tuple[int, ...], dtype[Any]]

gymnasium.spaces.utils.unflatten(space: Discrete, x: ndarray[tuple[int, ...], dtype[int64]]) → int64

gymnasium.spaces.utils.unflatten(space: MultiDiscrete, x: ndarray[tuple[int, ...], dtype[integer[Any]]]) → ndarray[tuple[int, ...], dtype[integer[Any]]]

gymnasium.spaces.utils.unflatten(space: Tuple, x: ndarray[tuple[int, ...], dtype[Any]] | tuple[Any, ...]) → tuple[Any, ...]

gymnasium.spaces.utils.unflatten(space: Dict, x: ndarray[tuple[int, ...], dtype[Any]] | dict[str, Any]) → dict[str, Any]

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

gymnasium.spaces.utils.unflatten(space: Text, x: ndarray[tuple[int, ...], dtype[int32]]) → str

gymnasium.spaces.utils.unflatten(space: Sequence, x: tuple[Any, ...]) → tuple[Any, ...] | Any

gymnasium.spaces.utils.unflatten(space: OneOf, x: ndarray[tuple[int, ...], dtype[Any]]) → tuple[int, Any]

Unflatten a data point from a space.

This reverses the transformation applied by 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.