Gymnasium Documentation

gymnasium.experimental.vector.utils.batch_space(space: Space[Any], n: int = 1) → Space[Any]#

gymnasium.experimental.vector.utils.batch_space(space: Box, n: int = 1)

gymnasium.experimental.vector.utils.batch_space(space: Discrete, n: int = 1)

gymnasium.experimental.vector.utils.batch_space(space: MultiDiscrete, n: int = 1)

gymnasium.experimental.vector.utils.batch_space(space: MultiBinary, n: int = 1)

gymnasium.experimental.vector.utils.batch_space(space: Tuple, n: int = 1)

gymnasium.experimental.vector.utils.batch_space(space: Dict, n: int = 1)

gymnasium.experimental.vector.utils.batch_space(space: Graph | Text | Sequence, n: int = 1)

Create a (batched) space, containing multiple copies of a single space.

Parameters:

space – Space (e.g. the observation space) for a single environment in the vectorized environment.
n – Number of environments in the vectorized environment.

Returns:

Space (e.g. the observation space)

Raises:

ValueError – Cannot batch space does not have a registered function.

Example

>>> from gymnasium.spaces import Box, Dict
>>> import numpy as np
>>> space = Dict({
...     'position': Box(low=0, high=1, shape=(3,), dtype=np.float32),
...     'velocity': Box(low=0, high=1, shape=(2,), dtype=np.float32)
... })
>>> batch_space(space, n=5)
Dict('position': Box(0.0, 1.0, (5, 3), float32), 'velocity': Box(0.0, 1.0, (5, 2), float32))

gymnasium.experimental.vector.utils.concatenate(space: Space, items: Iterable, out: tuple[Any, ...] | dict[str, Any] | np.ndarray) → tuple[Any, ...] | dict[str, Any] | np.ndarray#

gymnasium.experimental.vector.utils.concatenate(space: Box | Discrete | MultiDiscrete | MultiBinary, items: Iterable, out: np.ndarray) → np.ndarray

gymnasium.experimental.vector.utils.concatenate(space: Tuple, items: Iterable, out: tuple[Any, ...]) → tuple[Any, ...]

gymnasium.experimental.vector.utils.concatenate(space: Dict, items: Iterable, out: dict[str, Any]) → dict[str, Any]

gymnasium.experimental.vector.utils.concatenate(space: Space, items: Iterable, out: None) → tuple[Any, ...]

Concatenate multiple samples from space into a single object.

Parameters:

space – Observation space of a single environment in the vectorized environment.
items – Samples to be concatenated.
out – The output object. This object is a (possibly nested) numpy array.

Returns:

The output object. This object is a (possibly nested)

Raises:

ValueError – Space

Example

>>> from gymnasium.spaces import Box
>>> import numpy as np
>>> space = Box(low=0, high=1, shape=(3,), seed=42, dtype=np.float32)
>>> out = np.zeros((2, 3), dtype=np.float32)
>>> items = [space.sample() for _ in range(2)]
>>> concatenate(space, items, out)
array([[0.77395606, 0.43887845, 0.85859793],
       [0.697368  , 0.09417735, 0.97562236]], dtype=float32)

gymnasium.experimental.vector.utils.iterate(space: Space[T_cov], items: Iterable[T_cov]) → Iterator#

gymnasium.experimental.vector.utils.iterate(space: Discrete, items: Iterable)

gymnasium.experimental.vector.utils.iterate(space: Box | MultiDiscrete | MultiBinary, items: np.ndarray)

gymnasium.experimental.vector.utils.iterate(space: Tuple, items: tuple[Any, ...])

gymnasium.experimental.vector.utils.iterate(space: Dict, items: dict[str, Any])

Iterate over the elements of a (batched) space.

Parameters:

space – Observation space of a single environment in the vectorized environment.
items – Samples to be concatenated.
out – The output object. This object is a (possibly nested) numpy array.

Returns:

The output object. This object is a (possibly nested)

Raises:

ValueError – Space is not an instance of gym.Space

Example

>>> from gymnasium.spaces import Box, Dict
>>> import numpy as np
>>> space = Dict({
... 'position': Box(low=0, high=1, shape=(2, 3), seed=42, dtype=np.float32),
... 'velocity': Box(low=0, high=1, shape=(2, 2), seed=42, dtype=np.float32)})
>>> items = space.sample()
>>> it = iterate(space, items)
>>> next(it)
OrderedDict([('position', array([0.77395606, 0.43887845, 0.85859793], dtype=float32)), ('velocity', array([0.77395606, 0.43887845], dtype=float32))])
>>> next(it)
OrderedDict([('position', array([0.697368  , 0.09417735, 0.97562236], dtype=float32)), ('velocity', array([0.85859793, 0.697368  ], dtype=float32))])
>>> next(it)
Traceback (most recent call last):
    ...
StopIteration

gymnasium.experimental.vector.utils.create_empty_array(space: Space, n: int = 1, fn: callable = np.zeros) → tuple[Any, ...] | dict[str, Any] | np.ndarray#

gymnasium.experimental.vector.utils.create_empty_array(space: Box, n: int = 1, fn=np.zeros) → ndarray

gymnasium.experimental.vector.utils.create_empty_array(space: Tuple, n: int = 1, fn=np.zeros) → tuple[Any, ...]

gymnasium.experimental.vector.utils.create_empty_array(space: Dict, n: int = 1, fn=np.zeros) → dict[str, Any]

gymnasium.experimental.vector.utils.create_empty_array(space: Graph, n: int = 1, fn=np.zeros) → tuple[gymnasium.spaces.graph.GraphInstance, ...]

gymnasium.experimental.vector.utils.create_empty_array(space: Text, n: int = 1, fn=np.zeros) → tuple[str, ...]

gymnasium.experimental.vector.utils.create_empty_array(space: Sequence, n: int = 1, fn=np.zeros) → tuple[Any, ...]

gymnasium.experimental.vector.utils.create_empty_array(space: ~gymnasium.spaces.space.Space, n=1, fn=<built-in function zeros>)

Create an empty (possibly nested) (normally numpy-based) array, used in conjunction with concatenate(..., out=array).

In most cases, the array will be contained within the batched space, however, this is not guaranteed.

Parameters:

space – Observation space of a single environment in the vectorized environment.
n – Number of environments in the vectorized environment. If None, creates an empty sample from space.
fn – Function to apply when creating the empty numpy array. Examples of such functions are np.empty or np.zeros.

Returns:

The output object. This object is a (possibly nested)

Raises:

ValueError – Space is not a valid gym.Space instance

Example

>>> from gymnasium.spaces import Box, Dict
>>> import numpy as np
>>> space = Dict({
... 'position': Box(low=0, high=1, shape=(3,), dtype=np.float32),
... 'velocity': Box(low=0, high=1, shape=(2,), dtype=np.float32)})
>>> create_empty_array(space, n=2, fn=np.zeros)
OrderedDict([('position', array([[0., 0., 0.],
       [0., 0., 0.]], dtype=float32)), ('velocity', array([[0., 0.],
       [0., 0.]], dtype=float32))])

Utility functions for vectorisation#