Table of Contents

Class SpaceUtils

Namespace
Gym.Spaces
Assembly
Gym.dll

Gymnasium's gymnasium.spaces.utils: flattening a space's elements into one array for learning code (Flatten(Space, object?)), back (Unflatten(Space, object?)), the space they flatten into (FlattenSpace(Space)) and its size (Flatdim(Space)), plus the dtype-and-shape equivalence vector envs check (IsSpaceDtypeShapeEquiv(Space, Space)).

public static class SpaceUtils
Inheritance
SpaceUtils
Inherited Members

Remarks

Each function dispatches on the space's type, as Gymnasium's singledispatch does: a subclass of a Gym.NET space takes its base's path, and an unknown custom space raises NotImplementedError. Spaces that cannot become one array (a Graph, a Sequence, a composite holding one) flatten to the same structure with flattened parts.

Every array returned is new and owned by the caller, also where Gymnasium returns a view of the input (unflatten of a box reshapes the input itself): the values are Gymnasium's, the memory is never shared. Reference: gymnasium/spaces/utils.py.

Methods

Flatdim(Space)

The number of entries the flattened space has (Gymnasium's flatdim): the element count of a box or MultiBinary, n of a Discrete (one-hot), the sum of nvec of a MultiDiscrete, the sum over a composite's subspaces, max_length of a Text, and one more than the largest subspace for a OneOf (its index comes first).

public static long Flatdim(Space space)

Parameters

space Space

The space.

Returns

long

The flattened size.

Exceptions

ValueError

Thrown for a space that cannot be flattened to an array (a graph, a sequence, or a composite holding one).

NotImplementedError

Thrown for a custom space flattenable but unknown to this function.

ArgumentNullException

Thrown when space is null.

Flatten(Space, object?)

Flattens an element of space (Gymnasium's flatten): a box or MultiBinary element raveled in its dtype, a Discrete or MultiDiscrete element one-hot encoded, a Text as character indexes padded with the charset's size, a OneOf pair as its index followed by the padded flattened value, and a composite's parts concatenated.

public static object? Flatten(Space space, object? x)

Parameters

space Space

The space.

x object

The element: an array, a 0-d array or integer, a tuple (object?[]), a dict, a string, a GraphInstance.

Returns

object

A new array for a flattenable space; for a Graph a new GraphInstance of flattened nodes and edges; for a Sequence a tuple of flattened items (or their stacked array); for a composite that cannot become an array, a tuple or Info of flattened parts. The caller owns it.

Exceptions

IndexError

Thrown for a discrete value outside the space, or a text longer than max_length, with NumPy's message.

KeyError

Thrown for a dict element missing a key, or a character outside a text space's charset.

ValueError

Thrown for a tuple element of another length than the space (Python's zip(strict=True)).

TypeError

Thrown for a dict space given something that is not a mapping, or a text space given something that is not a string, with Python's messages.

NotImplementedError

Thrown for a custom space.

ArgumentNullException

Thrown when space is null.

FlattenSpace(Space)

The space Flatten(Space, object?) maps space's elements into (Gymnasium's flatten_space): a flat Box for every space that flattens to an array, and for the others the same structure (Tuple, Dict, Graph, Sequence) over flattened subspaces.

public static Space FlattenSpace(Space space)

Parameters

space Space

The space.

Returns

Space

A new space, owned by the caller, unseeded.

Remarks

Sampling the flattened space is not sampling the original: a flattened Discrete is a 0/1 box whose samples are rarely one-hot, as Gymnasium warns.

Exceptions

NotImplementedError

Thrown for a custom space.

ArgumentNullException

Thrown when space is null.

IsSpaceDtypeShapeEquiv(Space, Space)

Whether two spaces share a dtype and shape and whatever else decides an element's layout (Gymnasium's is_space_dtype_shape_equiv): vector envs require it of their sub-envs' spaces. Simple spaces compare their exact type, shape and dtype; a Text its length and charset; composites recurse.

public static bool IsSpaceDtypeShapeEquiv(Space space1, Space space2)

Parameters

space1 Space

The first space; its type decides the comparison, as Gymnasium dispatches on it.

space2 Space

The second space.

Returns

bool

true when equivalent.

Exceptions

NotImplementedError

Thrown for a custom first space, with Gymnasium's message.

TypeError

Thrown when either argument is null (Gymnasium's bare TypeError()).

Unflatten(Space, object?)

Reverses Flatten(Space, object?) for space (Gymnasium's unflatten); the space must be the one the element was flattened with.

public static object? Unflatten(Space space, object? x)

Parameters

space Space

The space.

x object

The flattened element: an array, or the tuple, dict or graph a non-flattenable space flattens to.

Returns

object

An element of space, new and owned by the caller.

Remarks

Not every array of the flattened space unflattens: a one-hot block with no 1 has no element, as in Gymnasium.

Exceptions

ValueError

Thrown for a flattened discrete element with no one-hot entry, with Gymnasium's message.

AssertionError

Thrown for a composite given the wrong flattened form (an array for a non-flattenable space or the reverse), with Gymnasium's messages.

KeyError

Thrown for a non-flattenable dict space's flattened dict missing a key.

NotImplementedError

Thrown for a custom space.

ArgumentNullException

Thrown when space is null.