Table of Contents

Class VectorUtils

Namespace
Gym.Vector
Assembly
Gym.dll

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

spaces IReadOnlyList<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

space Space

The space of one env's elements.

n int

The number of envs.

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

TypeError

Thrown when space is null, with Gymnasium's message.

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

space Space

The space of one env's elements.

items IEnumerable<object>

The elements, one per env.

out object

The destination (from CreateEmptyArray(Space, int, Func<Shape, DType, NDArray>?)): an array, a tuple or dict of them, or null for other spaces.

Returns

object

out filled, 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 space is 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

space Space

The space of one env's elements.

n int

The number of envs.

fn Func<Shape, DType, NDArray>

Creates an array of a shape and dtype; null is np.zeros, Gymnasium's default.

Returns

object

The empty batch, owned by the caller; null for an unknown custom space, as in Gymnasium.

Exceptions

TypeError

Thrown when space is null.

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

space Space

One sub-env's observation space.

n int

The number of sub-envs.

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 space is 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

space Space

The batched space (from BatchSpace(Space, int)).

items object

A 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

space Space

One sub-env's observation space.

sharedMemory object

The buffer CreateSharedMemory(Space, int) made for space.

n int

The 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 space is 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 sharedMemory is not the buffer of space.

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

sharedMemory object

The buffer, or null.

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

space Space

One sub-env's observation space.

index int

The sub-env, in [0, n).

value object

Its observation; read, never kept.

sharedMemory object

The 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 space is 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.