Composite Spaces#

Dict#

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

Dict.sample(mask: dict[str, Any] | None = None) → dict[str, Any]#

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`

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

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.

Tuple#

class gymnasium.spaces.Tuple(spaces: Iterable[Space[Any]], seed: int | Sequence[int] | np.random.Generator | None = 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.

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

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

Tuple.seed(seed: int | Sequence[int] | None = None) → list[int]#

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 of the subspaces.
List - Values used to seed the subspaces. This allows the seeding of multiple composite subspaces (List(42, 54, ...).

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

Sequence#

class gymnasium.spaces.Sequence(space: Space[Any], seed: int | np.random.Generator | None = 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::

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

Sequence.sample(mask: None | tuple[None | np.integer | npt.NDArray[np.integer], 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`.

Sequence.seed(seed: int | None = None) → list[int]#: Seed the PRNG of this space and the feature space.

Graph#

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:

self.observation_space = spaces.Graph(node_space=space.Box(low=-100, high=100, shape=(3,)), edge_space=spaces.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.

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

Graph.seed(seed: int | None = None) → list[int]#: Seed the PRNG of this space and possibly the PRNGs of subspaces.