unienv_interface.space.spaces.graph¶
Classes:
| Name | Description |
|---|---|
GraphInstance |
|
GraphSpace |
|
GraphInstance
dataclass
¶
GraphInstance(
n_nodes: BArrayType,
n_edges: Optional[BArrayType] = None,
nodes_features: Optional[BArrayType] = None,
edges_features: Optional[BArrayType] = None,
edges: Optional[BArrayType] = None,
)
Bases: Generic[BArrayType]
Attributes:
| Name | Type | Description |
|---|---|---|
n_nodes |
BArrayType
|
Number of nodes in the graph, shape (*batch_shape) |
n_edges |
Optional[BArrayType]
|
Number of edges in the graph, shape (*batch_shape) or None if no edges are present. |
nodes_features |
Optional[BArrayType]
|
Node features, shape (*batch_shape, max(n_nodes), *node_feature_space.shape) if node_feature_space is not None, otherwise None. |
edges_features |
Optional[BArrayType]
|
Edge features, shape (*batch_shape, max(n_edges), *edge_feature_space.shape) if edge_feature_space is not None, otherwise None. |
edges |
Optional[BArrayType]
|
Edges in the graph, shape (*batch_shape, max(n_edges), 2) where each edge is represented by a pair of node indices, or None if no edges are present. |
n_edges
class-attribute
instance-attribute
¶
Number of edges in the graph, shape (*batch_shape) or None if no edges are present.
nodes_features
class-attribute
instance-attribute
¶
Node features, shape (*batch_shape, max(n_nodes), *node_feature_space.shape) if node_feature_space is not None, otherwise None.
edges_features
class-attribute
instance-attribute
¶
Edge features, shape (*batch_shape, max(n_edges), *edge_feature_space.shape) if edge_feature_space is not None, otherwise None.
edges
class-attribute
instance-attribute
¶
Edges in the graph, shape (*batch_shape, max(n_edges), 2) where each edge is represented by a pair of node indices, or None if no edges are present.
GraphSpace
¶
GraphSpace(
backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
node_feature_space: Optional[
BoxSpace[BArrayType, BDeviceType, BDtypeType, BRNGType]
],
edge_feature_space: Optional[
BoxSpace[BArrayType, BDeviceType, BDtypeType, BRNGType]
] = None,
is_edge: bool = False,
min_nodes: int = 1,
max_nodes: Optional[int] = None,
min_edges: int = 1,
max_edges: Optional[int] = None,
batch_shape: Sequence[int] = (),
device: Optional[BDeviceType] = None,
metadata: Optional[Mapping[str, Any]] = None,
)
Bases: Space[GraphInstance[BArrayType], BDeviceType, BDtypeType, BRNGType], Generic[BArrayType, BDeviceType, BDtypeType, BRNGType]
Methods:
| Name | Description |
|---|---|
to |
|
sample |
|
create_empty |
|
is_bounded |
|
contains |
Return boolean specifying if x is a valid member of this space. |
clip |
Project the (possibly batched) graph |
get_repr |
|
is_subspaceeq |
Return whether this graph space is a non-strict subspace of |
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 |
abbr_device |
Return the shared device across spaces, or |
Attributes:
| Name | Type | Description |
|---|---|---|
batch_shape |
|
|
is_edge |
|
|
node_feature_space |
|
|
edge_feature_space |
|
|
min_nodes |
|
|
max_nodes |
|
|
min_edges |
|
|
max_edges |
|
|
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. |
node_feature_space
instance-attribute
¶
node_feature_space = (
node_feature_space
if (device is None or node_feature_space is None)
else node_feature_space.to(device=device)
)
edge_feature_space
instance-attribute
¶
edge_feature_space = (
edge_feature_space
if (device is None or edge_feature_space is None)
else edge_feature_space.to(device=device)
)
metadata
property
¶
metadata: SpaceMetadata
Read-only description of the data (see "Metadata" in the class docstring); empty if none was given.
shape
property
¶
Return the shape of the space as an immutable property.
to
¶
to(
backend: Optional[ComputeBackend] = None,
device: Optional[Union[BDeviceType, Any]] = None,
) -> Union[GraphSpace[BArrayType, BDeviceType, BDtypeType, BRNGType], GraphSpace]
contains
¶
contains(x: GraphInstance[BArrayType]) -> bool
Return boolean specifying if x is a valid member of this space.
clip
¶
clip(x: GraphInstance[BArrayType]) -> GraphInstance[BArrayType]
Project the (possibly batched) graph x onto this graph space (see Space.clip).
- Graphs with more than
max_nodesnodes keep their firstmax_nodesnodes; edges touching a dropped node are dropped too. Kept nodes keep their index, so the remaining edges stay valid. - Graphs with more than
max_edges(remaining) edges keep their firstmax_edgesedges, in order. The edge arrays are compacted per graph (dropped edges move into the padding). - Node / edge features are clamped with the feature spaces (padding
included, as
containschecks it); edge features are dropped if this space has no edge feature space.
Every graph of a batch (batch_shape) is handled separately; the
padded node / edge axes shrink to the largest remaining count. Returns
a new GraphInstance; unchanged arrays are shared with x.
Raises ValueError if x is not a GraphInstance of this
batch shape, lacks node features or (for spaces with edges) edges, or
if some graph has fewer than min_nodes nodes or, after dropping,
fewer than min_edges edges (nodes and edges cannot be invented).
get_repr
¶
is_subspaceeq
¶
Return whether this graph space is a non-strict subspace of other (⊆).
True iff other is a GraphSpace on the same backend, the node
and edge feature spaces are subspaces recursively, and self's
node/edge count ranges are contained within other's:
other.min_nodes <= self.min_nodesandself.max_nodes <= other.max_nodes(treatingNoneas +∞);- likewise for edges, with the additional requirement that
self.is_edgeandother.is_edgeagree (an edge-less space cannot be a subspace of an edge-bearing one and vice versa); the edge counts are ignored for edge-less spaces.
device is ignored.
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).