Composite Spaces

class gymnasium.spaces.Dict(spaces: None | dict[str, Space] | Sequence[tuple[str, Space]] = None, seed: dict | int | np.random.Generator | None = None, **spaces_kwargs: Space)[source]

A dictionary of Space instances.

Elements of this space are (ordered) dictionaries of elements from the constituent spaces.

Example

>>> from gymnasium.spaces import Dict, Box, Discrete
>>> observation_space = Dict({"position": Box(-1, 1, shape=(2,)), "color": Discrete(3)}, seed=42)
>>> observation_space.sample()
{'color': 0, 'position': array([-0.3991573 ,  0.21649833], dtype=float32)}

With a nested dict:

>>> from gymnasium.spaces import Box, Dict, Discrete, MultiBinary, MultiDiscrete
>>> Dict(  
...     {
...         "ext_controller": MultiDiscrete([5, 2, 2]),
...         "inner_state": Dict(
...             {
...                 "charge": Discrete(100),
...                 "system_checks": MultiBinary(10),
...                 "job_status": Dict(
...                     {
...                         "task": Discrete(5),
...                         "progress": Box(low=0, high=100, shape=()),
...                     }
...                 ),
...             }
...         ),
...     }
... )

It can be convenient to use Dict spaces if you want to make complex observations or actions more human-readable. Usually, it will not be possible to use elements of this space directly in learning code. However, you can easily convert Dict observations to flat arrays by using a gymnasium.wrappers.FlattenObservation wrapper. Similar wrappers can be implemented to deal with Dict actions.

Parameters:

  • spaces – A dictionary of spaces. This specifies the structure of the Dict space

  • seed – Optionally, you can use this argument to seed the RNGs of the spaces that make up the Dict space.

  • **spaces_kwargs – If spaces is None, you need to pass the constituent spaces as keyword arguments, as described above.

sample(mask: dict[str, Any] | None = None) → dict[str, Any][source]

Generates a single random sample from this space.

The sample is an ordered dictionary of independent samples from the constituent spaces.

Parameters:

mask – An optional mask for each of the subspaces, expects the same keys as the space

Returns:

A dictionary with the same key and sampled values from :attr:`self.spaces`

seed(seed: dict[str, Any] | int | None = None) → list[int][source]

Seed the PRNG of this space and all subspaces.

Depending on the type of seed, the subspaces will be seeded differently

  • None - All the subspaces will use a random initial seed

  • Int - The integer is used to seed the Dict space that is used to generate seed values for each of the subspaces. Warning, this does not guarantee unique seeds for all of the subspaces.

  • Dict - Using all the keys in the seed dictionary, the values are used to seed the subspaces. This allows the seeding of multiple composite subspaces (Dict["space": Dict[...], ...] with {"space": {...}, ...}).

Parameters:

seed – An optional list of ints or int to seed the (sub-)spaces.

class gymnasium.spaces.Tuple(spaces: Iterable[Space[Any]], seed: int | Sequence[int] | np.random.Generator | None = None)[source]

A tuple (more precisely: the cartesian product) of Space instances.

Elements of this space are tuples of elements of the constituent spaces.

Example

>>> from gymnasium.spaces import Tuple, Box, Discrete
>>> observation_space = Tuple((Discrete(2), Box(-1, 1, shape=(2,))), seed=42)
>>> observation_space.sample()
(0, array([-0.3991573 ,  0.21649833], dtype=float32))
Parameters:

  • spaces (Iterable[Space]) – The spaces that are involved in the cartesian product.

  • seed – Optionally, you can use this argument to seed the RNGs of the spaces to ensure reproducible sampling.

sample(mask: tuple[Any | None, ...] | None = None) → tuple[Any, ...][source]

Generates a single random sample inside this space.

This method draws independent samples from the subspaces.

Parameters:

mask – An optional tuple of optional masks for each of the subspace’s samples, expects the same number of masks as spaces

Returns:

Tuple of the subspace’s samples

seed(seed: int | Sequence[int] | None = None) → list[int][source]

Seed the PRNG of this space and all subspaces.

Depending on the type of seed, the subspaces will be seeded differently

  • None - All the subspaces will use a random initial seed

  • Int - The integer is used to seed the Tuple space that is used to generate seed values for each of the subspaces. Warning, this does not guarantee unique seeds for all the subspaces.

  • List - Values used to seed the subspaces. This allows the seeding of multiple composite subspaces [42, 54, ...].

Parameters:

seed – An optional list of ints or int to seed the (sub-)spaces.

class gymnasium.spaces.Sequence(space: Space[Any], seed: int | np.random.Generator | None = None, stack: bool = False)[source]

This space represent sets of finite-length sequences.

This space represents the set of tuples of the form \((a_0, \dots, a_n)\) where the \(a_i\) belong to some space that is specified during initialization and the integer \(n\) is not fixed

Example

>>> from gymnasium.spaces import Sequence, Box
>>> observation_space = Sequence(Box(0, 1), seed=2)
>>> observation_space.sample()
(array([0.26161215], dtype=float32),)
>>> observation_space = Sequence(Box(0, 1), seed=0)
>>> observation_space.sample()
(array([0.6369617], dtype=float32), array([0.26978672], dtype=float32), array([0.04097353], dtype=float32))
Parameters:

  • space – Elements in the sequences this space represent must belong to this space.

  • seed – Optionally, you can use this argument to seed the RNG that is used to sample from the space.

  • stack – If True then the resulting samples would be stacked.

sample(mask: None | tuple[None | np.integer | NDArray[np.integer], Any] = None) → tuple[Any] | Any[source]

Generates a single random sample from this space.

Parameters:

mask –

An optional mask for (optionally) the length of the sequence and (optionally) the values in the sequence. If you specify mask, it is expected to be a tuple of the form (length_mask, sample_mask) where length_mask is

  • None The length will be randomly drawn from a geometric distribution

  • np.ndarray of integers, in which case the length of the sampled sequence is randomly drawn from this array.

  • int for a fixed length sample

The second element of the mask tuple sample mask specifies a mask that is applied when sampling elements from the base space. The mask is applied for each feature space sample.

Returns:

A tuple of random length with random samples of elements from the :attr:`feature_space`.

seed(seed: int | None = None) → list[int][source]

Seed the PRNG of this space and the feature space.

class gymnasium.spaces.Graph(node_space: Box | Discrete, edge_space: None | Box | Discrete, seed: int | np.random.Generator | None = None)[source]

A space representing graph information as a series of nodes connected with edges according to an adjacency matrix represented as a series of edge_links.

Example

>>> from gymnasium.spaces import Graph, Box, Discrete
>>> observation_space = Graph(node_space=Box(low=-100, high=100, shape=(3,)), edge_space=Discrete(3), seed=42)
>>> observation_space.sample()
GraphInstance(nodes=array([[-12.224312 ,  71.71958  ,  39.473606 ],
       [-81.16453  ,  95.12447  ,  52.22794  ],
       [ 57.21286  , -74.37727  ,  -9.922812 ],
       [-25.840395 ,  85.353    ,  28.773024 ],
       [ 64.55232  , -11.317161 , -54.552258 ],
       [ 10.916958 , -87.23655  ,  65.52624  ],
       [ 26.33288  ,  51.61755  , -29.094807 ],
       [ 94.1396   ,  78.62422  ,  55.6767   ],
       [-61.072258 ,  -6.6557994, -91.23925  ],
       [-69.142105 ,  36.60979  ,  48.95243  ]], dtype=float32), edges=array([2, 0, 1, 1, 0, 0, 1, 0]), edge_links=array([[7, 5],
       [6, 9],
       [4, 1],
       [8, 6],
       [7, 0],
       [3, 7],
       [8, 4],
       [8, 8]], dtype=int32))
Parameters:

  • node_space (Union[Box, Discrete]) – space of the node features.

  • edge_space (Union[None, Box, Discrete]) – space of the edge features.

  • seed – Optionally, you can use this argument to seed the RNG that is used to sample from the space.

sample(mask: None | tuple[NDArray[Any] | tuple[Any, ...] | None, NDArray[Any] | tuple[Any, ...] | None] = None, num_nodes: int = 10, num_edges: int | None = None) → GraphInstance[source]

Generates a single sample graph with num_nodes between 1 and 10 sampled from the Graph.

Parameters:

  • mask – An optional tuple of optional node and edge mask that is only possible with Discrete spaces (Box spaces don’t support sample masks). If no num_edges is provided then the edge_mask is multiplied by the number of edges

  • num_nodes – The number of nodes that will be sampled, the default is 10 nodes

  • num_edges – An optional number of edges, otherwise, a random number between 0 and \(num_nodes^2\)

Returns:

A :class:`GraphInstance` with attributes `.nodes`, `.edges`, and `.edge_links`.

seed(seed: int | None = None) → list[int]

Seed the PRNG of this space and possibly the PRNGs of subspaces.

class gymnasium.spaces.OneOf(spaces: Iterable[Space[Any]], seed: int | Sequence[int] | np.random.Generator | None = None)[source]

An exclusive tuple (more precisely: the direct sum) of Space instances.

Elements of this space are elements of one of the constituent spaces.

Example

>>> from gymnasium.spaces import OneOf, Box, Discrete
>>> observation_space = OneOf((Discrete(2), Box(-1, 1, shape=(2,))), seed=42)
>>> observation_space.sample()  # the first element is the space index (Box in this case) and the second element is the sample from Box
(1, array([-0.3991573 ,  0.21649833], dtype=float32))
>>> observation_space.sample()  # this time the Discrete space was sampled as index=0
(0, 0)
>>> observation_space[0]
Discrete(2)
>>> observation_space[1]
Box(-1.0, 1.0, (2,), float32)
>>> len(observation_space)
2
Parameters:

  • spaces (Iterable[Space]) – The spaces that are involved in the cartesian product.

  • seed – Optionally, you can use this argument to seed the RNGs of the spaces to ensure reproducible sampling.

sample(mask: tuple[Any | None, ...] | None = None) → tuple[int, Any][source]

Generates a single random sample inside this space.

This method draws independent samples from the subspaces.

Parameters:

mask – An optional tuple of optional masks for each of the subspace’s samples, expects the same number of masks as spaces

Returns:

Tuple of the subspace’s samples

seed(seed: int | Sequence[int] | None = None) → list[int][source]

Seed the PRNG of this space and all subspaces.

Depending on the type of seed, the subspaces will be seeded differently

  • None - All the subspaces will use a random initial seed

  • Int - The integer is used to seed the Tuple space that is used to generate seed values for each of the subspaces. Warning, this does not guarantee unique seeds for all the subspaces.

  • List - Values used to seed the subspaces. This allows the seeding of multiple composite subspaces [42, 54, ...].

Parameters:

seed – An optional list of ints or int to seed the (sub-)spaces.