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': 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 convertDict
observations to flat arrays by using agymnasium.wrappers.FlattenObservation
wrapper. Similar wrappers can be implemented to deal withDict
actions.- Parameters:
spaces – A dictionary of spaces. This specifies the structure of the
Dict
spaceseed – Optionally, you can use this argument to seed the RNGs of the spaces that make up the
Dict
space.**spaces_kwargs – If
spaces
isNone
, 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 seedInt
- The integer is used to seed theDict
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 | Sequence[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 seedInt
- The integer is used to seed theTuple
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
/Tuple
- 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)
wherelength_mask
isNone
The length will be randomly drawn from a geometric distributionnp.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 seedInt
- The integer is used to seed theSequence
space that is used to generate a seed value for the feature space.Tuple of ints
- A tuple for theSequence
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
- 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 withedges
according to an adjacency matrix represented as a series ofedge_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:
- 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
and10
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 theedge_mask
is multiplied by the number of edgesnum_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 initializedInt
- The integer is used to seed theGraph
space that is used to generate seed values for the node and edge subspaces.Tuple[int, int]
- Seeds theGraph
and node subspace with a particular value. Only if edge subspace isn’t specifiedTuple[int, int, int]
- Seeds theGraph
, 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 seedInt
- The integer is used to seed theTuple
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