Composite Spaces¶

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': np.int64(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: int | dict[str, Any] | None = None) → dict[str, 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 subspaces, though is very unlikely.
Dict - A dictionary of seeds for each subspace, requires a seed key for every subspace. This supports seeding of multiple composite subspaces (Dict["space": Dict[...], ...] with {"space": {...}, ...}).

Parameters:: seed – An optional int or dictionary of subspace keys to int to seed each PRNG. See above for more details.
Returns:: A dictionary for the seed values of the subspaces

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()
(np.int64(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 | tuple[int] | None = None) → tuple[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.
Returns:: A tuple of the seed values for all subspaces

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=0)
>>> observation_space.sample()
(array([0.6822636], dtype=float32), array([0.18933342], dtype=float32), array([0.19049619], dtype=float32))
>>> observation_space.sample()
(array([0.83506], dtype=float32), array([0.9053838], dtype=float32), array([0.5836242], dtype=float32), array([0.63214064], dtype=float32))

Example with stacked observations

>>> observation_space = Sequence(Box(0, 1), stack=True, seed=0)
>>> observation_space.sample()
array([[0.6822636 ],
       [0.18933342],
       [0.19049619]], 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 | tuple[int, int] | None = None) → tuple[int, int][source]¶

Seed the PRNG of the Sequence space and the feature space.

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 Sequence space that is used to generate a seed value for the feature space.
Tuple of ints - A tuple for the Sequence and feature space.

Parameters:: seed – An optional int or tuple of ints to seed the PRNG. See above for more details
Returns:: A tuple of the seeding values for the Sequence and feature space

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=123)
>>> observation_space.sample(num_nodes=4, num_edges=8)
GraphInstance(nodes=array([[ 36.47037 , -89.235794, -55.928024],
       [-63.125637, -64.81882 ,  62.4189  ],
       [ 84.669   , -44.68512 ,  63.950912],
       [ 77.97854 ,   2.594091, -51.00708 ]], dtype=float32), edges=array([2, 0, 2, 1, 2, 0, 2, 1]), edge_links=array([[3, 0],
       [0, 0],
       [0, 1],
       [0, 2],
       [1, 0],
       [1, 0],
       [0, 1],
       [0, 2]], 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.

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 | tuple[int, int] | tuple[int, int, int] | None = None) → tuple[int, int] | tuple[int, int, int][source]¶

Seeds the PRNG of this space and node / edge subspace.

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

None - The root, node and edge spaces PRNG are randomly initialized
Int - The integer is used to seed the Graph space that is used to generate seed values for the node and edge subspaces.
Tuple[int, int] - Seeds the Graph and node subspace with a particular value. Only if edge subspace isn’t specified
Tuple[int, int, int] - Seeds the Graph, node and edge subspaces with a particular value.

Parameters:: seed – An optional int or tuple of ints for this space and the node / edge subspaces. See above for more details.
Returns:: A tuple of two or three ints depending on if the edge subspace is specified.

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=123)
>>> observation_space.sample()  # the first element is the space index (Box in this case) and the second element is the sample from Box
(np.int64(0), np.int64(0))
>>> observation_space.sample()  # this time the Discrete space was sampled as index=0
(np.int64(1), array([-0.00711833, -0.7257502 ], dtype=float32))
>>> 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 | tuple[int, ...] | None = None) → tuple[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.
Tuple[int, ...] - Values used to seed the subspaces, first value seeds the OneOf and subsequent seed the subspaces. This allows the seeding of multiple composite subspaces [42, 54, ...].

Parameters:: seed – An optional int or tuple of ints to seed the OneOf space and subspaces. See above for more details.
Returns:: A tuple of ints used to seed the OneOf space and subspaces