Composite Spaces#

Dict#

class gymnasium.spaces.Dict(spaces: Optional[Union[Dict[str, Space], Sequence[Tuple[str, Space]]]] = None, seed: Optional[Union[dict, int, Generator]] = None, **spaces_kwargs: Space)#

A dictionary of Space instances.

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

Example usage:

>>> from gymnasium.spaces import Dict, Discrete
>>> observation_space = Dict({"position": Discrete(2), "velocity": Discrete(3)})
>>> observation_space.sample()
OrderedDict([('position', 1), ('velocity', 2)])

Example usage [nested]:

>>> 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 gym.wrappers.FlattenObservation wrapper. Similar wrappers can be implemented to deal with Dict actions.

Constructor of Dict space.

This space can be instantiated in one of two ways: Either you pass a dictionary of spaces to __init__() via the spaces argument, or you pass the spaces as separate keyword arguments (where you will need to avoid the keys spaces and seed)

Example:

>>> from gymnasium.spaces import Box, Discrete
>>> Dict({"position": Box(-1, 1, shape=(2,)), "color": Discrete(3)})
Dict(color:Discrete(3), position:Box(-1.0, 1.0, (2,), float32))
>>> Dict(position=Box(-1, 1, shape=(2,)), color=Discrete(3))
Dict(color:Discrete(3), position:Box(-1.0, 1.0, (2,), float32))
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: Optional[Dict[str, Any]] = None) → dict#

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`

Tuple#

class gymnasium.spaces.Tuple(spaces: Iterable[Space], seed: Optional[Union[int, Sequence[int], Generator]] = None)#

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

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

Example usage:

>>> from gymnasium.spaces import Box, Discrete
>>> observation_space = Tuple((Discrete(2), Box(-1, 1, shape=(2,))))
>>> observation_space.sample()
(0, array([0.03633198, 0.42370757], dtype=float32))

Constructor of Tuple space.

The generated instance will represent the cartesian product \(\text{spaces}[0] \times ... \times \text{spaces}[-1]\).

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: Optional[Tuple[Optional[ndarray], ...]] = None) → tuple#

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

Sequence#

class gymnasium.spaces.Sequence(space: Space, seed: Optional[Union[int, Generator]] = None)#

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::
>>> space = Sequence(Box(0, 1))
>>> space.sample()
(array([0.0259352], dtype=float32),)
>>> space.sample()
(array([0.80977976], dtype=float32), array([0.80066574], dtype=float32), array([0.77165383], dtype=float32))

Constructor of the Sequence space.

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.

sample(mask: Optional[Tuple[Optional[Union[ndarray, int]], Optional[Any]]] = None) → Tuple[Any]#

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

Graph#

class gymnasium.spaces.Graph(node_space: Union[Box, Discrete], edge_space: Union[None, Box, Discrete], seed: Optional[Union[int, Generator]] = None)#

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

>>> from gymnasium.spaces import Box, Discrete
>>> Graph(node_space=Box(low=-100, high=100, shape=(3,)), edge_space=Discrete(3))

Constructor of Graph.

The argument node_space specifies the base space that each node feature will use. This argument must be either a Box or Discrete instance.

The argument edge_space specifies the base space that each edge feature will use. This argument must be either a None, Box or Discrete instance.

Parameters:

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

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

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

sample(mask: Optional[Tuple[Optional[Union[ndarray, tuple]], Optional[Union[ndarray, tuple]]]] = None, num_nodes: int = 10, num_edges: Optional[int] = None) → GraphInstance#

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 NamedTuple representing a graph with attributes .nodes, .edges, and .edge_links.