Spaces Vector Utils

gymnasium.vector.utils.batch_space(space: Space, n: int = 1) → Space

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

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

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

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

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

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

gymnasium.vector.utils.batch_space(space: Space, n=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 that 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)
... })
>>> 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.vector.utils.concatenate(space: Space, items: Iterable, out: tuple | dict | ndarray) → tuple | dict | ndarray

gymnasium.vector.utils.concatenate(space: MultiBinary, items, out)

gymnasium.vector.utils.concatenate(space: MultiDiscrete, items, out)

gymnasium.vector.utils.concatenate(space: Discrete, items, out)

gymnasium.vector.utils.concatenate(space: Box, items, out)

gymnasium.vector.utils.concatenate(space: Tuple, items, out)

gymnasium.vector.utils.concatenate(space: Dict, items, out)

gymnasium.vector.utils.concatenate(space: Space, items, out)

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 is not a valid gym.Space instance

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.vector.utils.iterate(space: Space, items) → Iterator

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

gymnasium.vector.utils.iterate(space: MultiBinary, items)

gymnasium.vector.utils.iterate(space: MultiDiscrete, items)

gymnasium.vector.utils.iterate(space: Box, items)

gymnasium.vector.utils.iterate(space: Tuple, items)

gymnasium.vector.utils.iterate(space: Dict, items)

gymnasium.vector.utils.iterate(space: Space, items)

Iterate over the elements of a (batched) space.

Parameters:

• space – Space to which items belong to.

• items – Items to be iterated over.

Returns:

Iterator over the elements in `items`.

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

Shared Memory Utils

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

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

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

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

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

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

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

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

Create an empty (possibly nested) numpy array.

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))])

gymnasium.vector.utils.create_shared_memory(space: Space, n: int = 1, ctx=mp) → dict | tuple | Array

gymnasium.vector.utils.create_shared_memory(space: ~gymnasium.spaces.multi_binary.MultiBinary, n: int = 1, ctx=<module 'multiprocessing' from '/opt/hostedtoolcache/Python/3.9.16/x64/lib/python3.9/multiprocessing/__init__.py'>)

gymnasium.vector.utils.create_shared_memory(space: ~gymnasium.spaces.multi_discrete.MultiDiscrete, n: int = 1, ctx=<module 'multiprocessing' from '/opt/hostedtoolcache/Python/3.9.16/x64/lib/python3.9/multiprocessing/__init__.py'>)

gymnasium.vector.utils.create_shared_memory(space: ~gymnasium.spaces.discrete.Discrete, n: int = 1, ctx=<module 'multiprocessing' from '/opt/hostedtoolcache/Python/3.9.16/x64/lib/python3.9/multiprocessing/__init__.py'>)

gymnasium.vector.utils.create_shared_memory(space: ~gymnasium.spaces.box.Box, n: int = 1, ctx=<module 'multiprocessing' from '/opt/hostedtoolcache/Python/3.9.16/x64/lib/python3.9/multiprocessing/__init__.py'>)

gymnasium.vector.utils.create_shared_memory(space: ~gymnasium.spaces.tuple.Tuple, n: int = 1, ctx=<module 'multiprocessing' from '/opt/hostedtoolcache/Python/3.9.16/x64/lib/python3.9/multiprocessing/__init__.py'>)

gymnasium.vector.utils.create_shared_memory(space: ~gymnasium.spaces.dict.Dict, n=1, ctx=<module 'multiprocessing' from '/opt/hostedtoolcache/Python/3.9.16/x64/lib/python3.9/multiprocessing/__init__.py'>)

Create a shared memory object, to be shared across processes.

This eventually contains the observations from the vectorized environment.

Parameters:

• space – Observation space of a single environment in the vectorized environment.

• n – Number of environments in the vectorized environment (i.e. the number of processes).

• ctx – The multiprocess module

Returns:

shared_memory for the shared object across processes.

Raises:

CustomSpaceError – Space is not a valid gymnasium.Space instance

gymnasium.vector.utils.read_from_shared_memory(space: Space, shared_memory: dict | tuple | Array, n: int = 1) → dict | tuple | ndarray

gymnasium.vector.utils.read_from_shared_memory(space: MultiBinary, shared_memory, n: int = 1)

gymnasium.vector.utils.read_from_shared_memory(space: MultiDiscrete, shared_memory, n: int = 1)

gymnasium.vector.utils.read_from_shared_memory(space: Discrete, shared_memory, n: int = 1)

gymnasium.vector.utils.read_from_shared_memory(space: Box, shared_memory, n: int = 1)

gymnasium.vector.utils.read_from_shared_memory(space: Tuple, shared_memory, n: int = 1)

gymnasium.vector.utils.read_from_shared_memory(space: Dict, shared_memory, n: int = 1)

Read the batch of observations from shared memory as a numpy array.

..notes::

The numpy array objects returned by read_from_shared_memory shares the memory of shared_memory. Any changes to shared_memory are forwarded to observations, and vice-versa. To avoid any side-effect, use np.copy.

Parameters:

• space – Observation space of a single environment in the vectorized environment.

• shared_memory – Shared object across processes. This contains the observations from the vectorized environment. This object is created with create_shared_memory.

• n – Number of environments in the vectorized environment (i.e. the number of processes).

Returns:

Batch of observations as a (possibly nested)

Raises:

CustomSpaceError – Space is not a valid gymnasium.Space instance

gymnasium.vector.utils.write_to_shared_memory(space: Space, index: int, value: ndarray, shared_memory: dict | tuple | Array)

gymnasium.vector.utils.write_to_shared_memory(space: MultiBinary, index, value, shared_memory)

gymnasium.vector.utils.write_to_shared_memory(space: MultiDiscrete, index, value, shared_memory)

gymnasium.vector.utils.write_to_shared_memory(space: Discrete, index, value, shared_memory)

gymnasium.vector.utils.write_to_shared_memory(space: Box, index, value, shared_memory)

gymnasium.vector.utils.write_to_shared_memory(space: Tuple, index, values, shared_memory)

gymnasium.vector.utils.write_to_shared_memory(space: Dict, index, values, shared_memory)

Write the observation of a single environment into shared memory.

Parameters:

• space – Observation space of a single environment in the vectorized environment.

• index – Index of the environment (must be in [0, num_envs)).

• value – Observation of the single environment to write to shared memory.

• shared_memory – Shared object across processes. This contains the observations from the vectorized environment. This object is created with create_shared_memory.

Raises:

CustomSpaceError – Space is not a valid gymnasium.Space instance