Class SpaceUtils
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
spaceSpaceThe 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
spaceis 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
spaceSpaceThe space.
xobjectThe 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
spaceis 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
spaceSpaceThe 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
spaceis 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
space1SpaceThe first space; its type decides the comparison, as Gymnasium dispatches on it.
space2SpaceThe second space.
Returns
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
spaceSpaceThe space.
xobjectThe 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
spaceis null.