Skip to content

unienv_interface.space.spaces.dict

Implementation of a space that represents the cartesian product of other spaces as a dictionary.

Classes:

Name Description
DictSpace

Cartesian product of named subspaces represented as a mapping.

DictSpace

DictSpace(
    backend: ComputeBackend[Any, BDeviceType, BDtypeType, BRNGType],
    spaces: Optional[
        Union[
            Dict[str, Space[Any, BDeviceType, BDtypeType, BRNGType]],
            Sequence[Tuple[str, Space[Any, BDeviceType, BDtypeType, BRNGType]]],
        ]
    ] = None,
    device: Optional[BDeviceType] = None,
    metadata: Optional[Mapping[str, Any]] = None,
)

Bases: Space[Dict[str, Any], BDeviceType, BDtypeType, BRNGType]

Cartesian product of named subspaces represented as a mapping.

Create a dictionary-valued space from named child spaces.

metadata describes the dict as a whole; every child keeps its own.

Methods:

Name Description
to
sample
create_empty

Create an empty data structure for this space.

is_bounded
contains

Return boolean specifying if x is a valid member of this space.

clip

Project x onto this dict space (see Space.clip).

is_subspaceeq

Return whether this dict space is a non-strict subspace of other (⊆).

get_repr
keys

Returns the keys of the Dict.

data_to
with_metadata

Return a copy of this space with updated metadata (this space is left unchanged).

is_subspace

Return whether this space is a STRICT subspace of other (self ⊂ other).

abbr_device

Return the shared device across spaces, or None if mixed/empty.

Attributes:

Name Type Description
spaces
device Optional[_SpaceBDeviceT]
metadata SpaceMetadata

Read-only description of the data (see "Metadata" in the class docstring); empty if none was given.

shape tuple[int, ...] | None

Return the shape of the space as an immutable property.

spaces instance-attribute

spaces = new_spaces

device property

device: Optional[_SpaceBDeviceT]

metadata property

metadata: SpaceMetadata

Read-only description of the data (see "Metadata" in the class docstring); empty if none was given.

shape property

shape: tuple[int, ...] | None

Return the shape of the space as an immutable property.

to

to(
    backend: Optional[ComputeBackend] = None,
    device: Optional[Union[BDeviceType, Any]] = None,
) -> Union[DictSpace[BDeviceType, BDtypeType, BRNGType], DictSpace]

sample

sample(rng: BDeviceType) -> Tuple[BDeviceType, Dict[str, Any]]

create_empty

create_empty() -> Dict[str, Any]

Create an empty data structure for this space.

is_bounded

is_bounded(manner='both')

contains

contains(x: Any) -> bool

Return boolean specifying if x is a valid member of this space.

clip

clip(x: Mapping[str, Any]) -> Dict[str, Any]

Project x onto this dict space (see Space.clip).

Keys of x that are not in this space are dropped and every value is clipped recursively with its subspace; the result is a new dict with exactly this space's keys. Raises ValueError if x is not a mapping or lacks one of this space's keys (it cannot be invented).

is_subspaceeq

is_subspaceeq(other: Any) -> bool

Return whether this dict space is a non-strict subspace of other (⊆).

True iff other is a DictSpace on the same backend, every key of self is present in other (self.keys() ⊆ other.keys()), and for every shared key self.spaces[k].is_subspaceeq(other.spaces[k]) holds recursively. Unlike contains, other is permitted to expose EXTRA keys beyond those of self — this is the controller required-observation-space use case where the environment may provide additional observation entries. device is ignored.

get_repr

get_repr(
    abbreviate: bool = False,
    include_backend: bool = True,
    include_device: bool = True,
    include_dtype: bool = True,
) -> str

keys

keys() -> KeysView

Returns the keys of the Dict.

data_to

data_to(data, backend=None, device=None)

with_metadata

with_metadata(
    metadata: Optional[Mapping[str, Any]] = None,
    /,
    *,
    replace: bool = False,
    **updates: Any,
) -> Space[SpaceDataT, _SpaceBDeviceT, _SpaceBDTypeT, _SpaceBDRNGT]

Return a copy of this space with updated metadata (this space is left unchanged).

metadata and updates are merged into the current metadata, or replace it entirely with replace=True (space.with_metadata(replace=True) clears it). Nested spaces are shared with this space, not copied.

is_subspace

is_subspace(other: Space) -> bool

Return whether this space is a STRICT subspace of other (self ⊂ other).

Defined uniformly for all spaces as::

self.is_subspace(other)  ⟺  self.is_subspaceeq(other) and not other.is_subspaceeq(self)

I.e. self ⊆ other holds but other ⊆ self does not, so self is a PROPER (strict) subspace of other. This is the ⊂ relation versus the non-strict ⊆ provided by :meth:is_subspaceeq.

This definition is used instead of relying on __eq__ because some space classes only have identity __eq__; defining strict containment via the symmetric non-strict check works uniformly for all classes regardless of their __eq__ implementation.

For structurally-distinct-but-mutually-containing spaces (which should not occur under the strict dtype/shape policies enforced by the per-class is_subspaceeq implementations) this degrades gracefully to False: if both self.is_subspaceeq(other) and other.is_subspaceeq(self) hold, the two spaces are considered equivalent and neither is a STRICT subspace of the other.

If either side's is_subspaceeq is not implemented (the base :meth:is_subspaceeq raises NotImplementedError), the exception propagates to the caller — it is NOT swallowed into False so that callers can tell that the comparison is unsupported.

Note: controller-required-space checks should typically use :meth:is_subspaceeq (a controller's required space may exactly equal the env space, in which case the strict is_subspace would return False).

abbr_device staticmethod

abbr_device(
    spaces: Iterable[Space[Any, _SpaceBDeviceT, _SpaceBDTypeT, _SpaceBDRNGT]],
) -> Optional[_SpaceBDeviceT]

Return the shared device across spaces, or None if mixed/empty.