Class VectorUtils
Gymnasium's gymnasium.vector.utils space functions: batching a space for n envs, iterating over and
concatenating batched samples, and allocating an empty batch. Vector envs use them for their batched spaces and
observations; Graph and a stacked Sequence sample through them.
public static class VectorUtils
- Inheritance
-
VectorUtils
- Inherited Members
Remarks
Each function dispatches on the space's type, as Gymnasium's singledispatch does: a subclass of a known space
takes its base's path, and an unknown custom space takes Gymnasium's fallback (a tuple of copies for
BatchSpace(Space, int), an error for Iterate(Space, object?)). Reference: gymnasium/vector/utils/space_utils.py.
Methods
BatchDifferingSpaces(IReadOnlyList<Space>)
One space for spaces that differ only in parameters (Gymnasium's batch_differing_spaces):
boxes stack their bounds, discrete spaces become a MultiDiscrete, composites batch per position or
key, and Graph, Text, Sequence and OneOf become a
Tuple of copies.
public static Space BatchDifferingSpaces(IReadOnlyList<Space> spaces)
Parameters
spacesIReadOnlyList<Space>The spaces, all of one type.
Returns
- Space
A new space, owned by the caller, starting from a copy of the first space's generator.
Exceptions
- ValueError
Thrown for an empty list, or spaces whose dtypes, shapes or keys differ, with Gymnasium's messages.
- TypeError
Thrown for spaces of different types, or a type with no batching.
BatchSpace(Space, int)
The space of n stacked elements of space (Gymnasium's batch_space):
a Box gains a leading axis, a Discrete becomes a MultiDiscrete, a
MultiDiscrete or MultiBinary a Box, composites batch their subspaces, and
any other space becomes a Tuple of n independently seeded copies.
public static Space BatchSpace(Space space, int n = 1)
Parameters
Returns
- Space
A new space, owned by the caller; it starts from a copy of
space's generator.
Remarks
Reading the space's generator creates it from entropy when the space was never seeded, as Gymnasium's
deepcopy(space.np_random) does. Reference: gymnasium/vector/utils/space_utils.py (batch_space).
Exceptions
Concatenate(Space, IEnumerable<object?>, object?)
Stacks per-env elements into a batch (Gymnasium's concatenate): arrays into out along a
new first axis, tuples and dicts per position or key, and other spaces into a tuple of the items.
public static object? Concatenate(Space space, IEnumerable<object?> items, object? @out)
Parameters
spaceSpaceThe space of one env's elements.
itemsIEnumerable<object>The elements, one per env.
outobjectThe destination (from CreateEmptyArray(Space, int, Func<Shape, DType, NDArray>?)): an array, a tuple or dict of them, or null for other spaces.
Returns
- object
outfilled, a new tuple or dict holding the filled parts, or a tuple of the items.
Remarks
An array space's items may be Python numbers, as np.stack takes them: an int stacks as int64 (uint64 above
MaxValue), a float as float64, a bool as bool, a .NET float as float32 (the
NumPy scalar it stands for); the batch then takes out's dtype.
Exceptions
- TypeError
Thrown when
spaceis null, or an array space's item is neither an array nor a Python number (Expected an array to concatenate, got <class 'str'>).- OverflowError
Thrown, as Python's
OverflowError, for an int beyond 64 bits, which NumPy would stack as an object.
CreateEmptyArray(Space, int, Func<Shape, DType, NDArray>?)
An empty batch for n envs (Gymnasium's create_empty_array): arrays of shape
(n,) + space.shape from fn, tuples and dicts of them, and placeholder tuples for spaces
whose batches are tuples.
public static object? CreateEmptyArray(Space space, int n = 1, Func<Shape, DType, NDArray>? fn = null)
Parameters
spaceSpaceThe space of one env's elements.
nintThe number of envs.
fnFunc<Shape, DType, NDArray>Creates an array of a shape and dtype; null is
np.zeros, Gymnasium's default.
Returns
Exceptions
CreateSharedMemory(Space, int)
Allocates the buffer an AsyncVectorEnv<TObs, TAct> with shared_memory collects its sub-envs'
observations in (Gymnasium's create_shared_memory): for an array space, one flat zeroed array of
n * prod(shape) elements of the space's dtype; a tuple of buffers for a Tuple, a dict of
them for a Dict, int32 character indices for a Text, and for a OneOf an
int64 array of the chosen subspaces followed by every subspace's buffer.
public static object CreateSharedMemory(Space space, int n = 1)
Parameters
Returns
- object
The buffer; the caller owns its arrays (ReleaseSharedMemory(object?) disposes them).
Remarks
Gymnasium's buffer is a multiprocessing array its worker processes write into. Gym.NET's workers are
threads of the same process, which share every array, so the buffer is an ordinary NumSharp array: what stays is
the layout, the dtypes (a float16 or bool space gets a float16 or bool buffer, where Python needs raw bytes or
c_bool) and the refusals, which decide whether AsyncVectorEnv(..., shared_memory=True) accepts a
space. Untyped ObjectSpace views are read through to the space they view.
Reference: gymnasium/vector/utils/shared_memory.py.
Exceptions
- ArgumentNullException
Thrown when
spaceis null.- TypeError
Thrown for a Graph or Sequence, whose shape varies, with Gymnasium's message.
- CustomSpaceError
Thrown for a space of any other class, with Gymnasium's message.
Iterate(Space, object?)
The elements of a batched sample, one per env (Gymnasium's iterate): an array's first axis, a batched
tuple's or dict's per-env tuples or dicts.
public static IEnumerable<object?> Iterate(Space space, object? items)
Parameters
spaceSpaceThe batched space (from BatchSpace(Space, int)).
itemsobjectA batched sample.
Returns
- IEnumerable<object>
The per-env elements; array elements are views into
items.
Exceptions
- TypeError
Thrown for a Discrete space, or items that cannot be iterated.
- CustomSpaceError
Thrown for a space type with no iteration.
ReadFromSharedMemory(Space, object, int)
The batch of observations a shared buffer holds (Gymnasium's read_from_shared_memory): for an array
space, a (n, *shape) view of the buffer, so later writes show through it; tuples and dicts of those for
Tuple and Dict; for a Text the decoded strings (a new tuple); for a
OneOf a tuple of (index, sample) pairs.
public static object? ReadFromSharedMemory(Space space, object sharedMemory, int n = 1)
Parameters
spaceSpaceOne sub-env's observation space.
sharedMemoryobjectThe buffer CreateSharedMemory(Space, int) made for
space.nintThe number of sub-envs.
Returns
- object
The batch: arrays that are views of the buffer (dispose them; the buffer stays its owner's), or object?[] / Info of them.
Remarks
A OneOf pair holds the chosen index as a 0-d int64 array (NumPy's np.int64) and the
index-th element of that subspace's batch: a row view for an array subspace, and, as in Gymnasium, the
index-th member of a tuple subspace's batch (not that sub-env's sample).
Reference: gymnasium/vector/utils/shared_memory.py.
Exceptions
- ArgumentNullException
Thrown when
spaceis null.- CustomSpaceError
Thrown for a space with no shared buffer, with Gymnasium's message.
- ValueError
Thrown when a tuple buffer holds another number of members than the space (Python's
zip(strict=True)text).- KeyError
Thrown for a OneOf whose chosen subspace is a Dict: Gymnasium indexes its batch by position, which a dict refuses.
- IndexError
Thrown for a OneOf whose chosen subspace is a tuple with fewer members than the sub-env's index, as in Gymnasium.
- InvalidCastException
Thrown when
sharedMemoryis not the buffer ofspace.
ReleaseSharedMemory(object?)
Disposes every array of a shared buffer: an array, or the arrays inside its tuples and dicts.
public static void ReleaseSharedMemory(object? sharedMemory)
Parameters
Remarks
Gymnasium's buffer is freed by the garbage collector; Gym.NET's owner releases it when it closes (D19).
WriteToSharedMemory(Space, int, object?, object)
Writes one sub-env's observation into its slot of a shared buffer (Gymnasium's write_to_shared_memory):
an array observation is cast to the space's dtype and flattened into elements
[index * size, (index + 1) * size); tuples and dicts write member by member; a text writes its flattened
character indices; a OneOf pair writes its index and, into that subspace's buffer only, its sample.
public static void WriteToSharedMemory(Space space, int index, object? value, object sharedMemory)
Parameters
spaceSpaceOne sub-env's observation space.
indexintThe sub-env, in
[0, n).valueobjectIts observation; read, never kept.
sharedMemoryobjectThe buffer CreateSharedMemory(Space, int) made for
space.
Remarks
Every sub-env writes its own disjoint slot, which is what lets Gymnasium's worker processes (and Gym.NET's worker threads) write the same buffer at once without a lock. Reference: gymnasium/vector/utils/shared_memory.py.
Exceptions
- ArgumentNullException
Thrown when
spaceis null.- ValueError
Thrown when a tuple observation's length differs from the space's (Python's
zip(strict=True)text), a OneOf value is not a pair, or the observation does not fit the slot.- TypeError
Thrown when a tuple or OneOf observation cannot be unpacked.
- CustomSpaceError
Thrown for a space with no shared buffer, with Gymnasium's message.