How to Consume Derived Graphs with Vanilla GNNs
The derived-graph encoders turn a planning problem's objects and atoms into
plain homogeneous PyTorch Geometric graphs. No heterogeneous machinery, custom
collation, or bespoke layer is required: the output is a stock Data object
whose node and edge features are integer-id channels that you embed with
nn.Embedding before message passing.
All facades take a problem (pymimir.Problem or a pytyr.PlanningTask),
not a bare Domain, because object tables are problem-scoped.
Which Facade Should I Use?
| If you want ... | Use | Notes |
|---|---|---|
| Reified atom nodes (star view) | StarGraphEncoder |
Object nodes plus one node per grounded literal/action anchor; position-aware star edges |
| A compact objects-only graph | ObjectGraphEncoder |
Atoms become fully labeled argument-pair edges via atom_expansion="clique" \| "chain" \| "star_first", plus an anchor node and the tuple instance table |
| Atom co-occurrence structure | AtomLineGraphEncoder |
Star universe plus fact-fact line_share edges bounded by line_graph_max_degree |
| Native hypergraph layers | HypergraphIncidenceEncoder |
Literal instances as hyperedges; emits hyperedge_index / hyperedge_attr_ids ([M, 6]) for PyG HypergraphConv |
| Transformer attention biases | TransformerBiasEncoder |
Objects-only clique projection plus sparse shortest-path fields spd_src / spd_dst / spd_dist (tune with spd_max_hops) |
TupleTensorEncoder additionally exposes a padding-free CSR tuple view
(tuple_args / tuple_ptr plus one id vector per node channel, also stacked
as tuple_attr_ids) — see its class docstring. ObjectGraphEncoder and
TransformerBiasEncoder carry the same tuple channels unconditionally,
because a pairwise projection cannot group the arguments of an arity >= 3
instance on its own.
TransformerBiasEncoder spd distances are even bipartite hop counts: two
objects sharing one fact sit at distance 2, and spd_max_hops must be >= 2.
Objects-only facades need an edge-conditioned layer
ObjectGraphEncoder and TransformerBiasEncoder reify no fact, goal,
subgoal or history node, so their x_ids is information-free: on
blocks/smedium it has 2 distinct rows for the whole graph (3 once
actions are supplied), and the only non-zero column is role. All of the
state content is on edge_attr and in the tuple instance table. Embedding
x_ids alone — the recipe below, applied naively — hands your model a
near-constant feature matrix. See
Objects-only facades: the content is on the edges.
Channel Contract
Every facade encodes to the same carrier layout:
x_ids:[N, 6]float tensor of integer node channelsedge_index:[2, E]edge_attr:[E, 9]float tensor of integer edge channels
There is deliberately no x — see There is no data.x.
Node channels, in column order (channel_names):
| Column | Name | Values |
|---|---|---|
| 0 | role |
index into vocab_roles = ["object", "fact", "goal", "subgoal", "history", "action", "anchor"] |
| 1 | relation_id_plus_one |
relation id + 1 over the unified space (see below); 0 means "none" |
| 2 | sign |
0 = positive literal, 1 = negated literal |
| 3 | goal_level |
small int goal/subgoal layer (0 = top goal) |
| 4 | history_dt |
history age — signed, negative for history rows |
| 5 | category |
index into vocab_categories = ["static", "fluent", "derived", "action"] |
Edge channels, in column order (edge_channel_names):
| Column | Name | Values |
|---|---|---|
| 0 | kind |
index into vocab_edge_kinds (13 entries, listed below) |
| 1 | pos_a |
argument position of the source endpoint |
| 2 | pos_b |
argument position of the target endpoint |
| 3 | rel_id_plus_one |
relation id + 1 of the instance this edge was derived from; 0 = none |
| 4 | role |
that instance's role id |
| 5 | sign |
that instance's sign |
| 6 | goal_level |
that instance's goal level |
| 7 | history_dt |
that instance's history age — signed |
| 8 | category |
that instance's category |
vocab_edge_kinds is
["arg_fwd", "arg_bwd", "clique_fwd", "clique_bwd", "chain_fwd", "chain_bwd",
"star_first_fwd", "star_first_bwd", "nullary_self", "action_fwd",
"action_bwd", "line_share", "unary_self"]
Columns 3..8 apply to every edge kind in every node universe, so an
objects-only projection edge is as self-describing as a star edge. The single
exception is line_share, whose columns 3..8 are all zero: it is not derived
from one instance but connects two reified fact nodes that already carry their
own six channels, so nothing is lost.
A node row is only populated when the encoder reifies a node for the
instance. Objects carry role 0 and zeros everywhere else — they have no
labels of their own — and in the objects-only universe there are no other
rows except the anchor, so columns 1..5 stay zero. Columns 1..5 of x_ids
therefore say something only in the star-shaped universes; see
Objects-only facades.
With the default include_metadata=True, the graph also carries plain Python
metadata attributes: vocab_roles, vocab_relations, vocab_predicates,
vocab_actions, vocab_edge_kinds, vocab_categories, num_predicates,
node_universe, atom_expansion, has_anchor, channel_names,
edge_channel_names, and (when export_node_names=True) node_names /
object_names. Pass include_metadata=False to emit tensors only — the
tensors still describe the state completely, but you lose the ability to
decode any id back to a name and to split the relation id space. The
vocabularies stay aligned across states of one problem, so per-channel
embedding sizes can be sized once from max + 2 headroom.
Column 1 is a unified relation space
Predicates and action schemas share one id space:
relation_id(predicate p) = p for p in 0 .. P - 1
relation_id(action schema a) = P + a P = data.num_predicates
vocab_relations names the whole space and equals
vocab_predicates + vocab_actions, so one embedding table of size
len(vocab_relations) + 1 covers nodes of every role. On blocks/smedium,
num_predicates is 7 with vocab_predicates == ["clear", "handempty",
"holding", "on", "ontable", "number", "object"] and vocab_actions ==
["pick-up", "put-down", "stack", "unstack"]; the fact (on a b) gets
relation_id_plus_one == 4 and the grounded action @(unstack a b) gets
11 — schema id 3 shifted by P, decoding through
vocab_relations[10] == "unstack".
Sizing that channel by max(len(vocab_predicates), len(action schemas)) + 1
was wrong and no amount of headroom fixed it: on blocks/smedium that
formula gives 8, and predicate id 3 (on) and action-schema id 3 (unstack)
still shared embedding row 3. Under the unified space the two are ids 3 and
10, and the correct size is len(vocab_relations) + 1 == 12. To recover the
old split without string compares:
rel = data.x_ids[:, 1].long() - 1 # -1 == "none"
is_action = rel >= data.num_predicates
schema_id = rel[is_action] - data.num_predicates
tuple_rel_ids and hyperedge_attr_ids[:, 1] index the same unified space
(tuple_rel_ids stores the raw relation id, with -1 for "none", while
x_ids, edge_attr[:, 3] and hyperedge_attr_ids[:, 1] all store id + 1).
Column 4 is the one signed channel
x_ids[:, 4] and edge_attr[:, 7] carry the history age exactly as supplied,
so history rows are negative. Every other channel is a non-negative id.
The naive nn.Embedding recipe therefore raises
IndexError: index out of range in self the moment history is present.
Each graph exports the shift you need:
| Field | Shape | Use |
|---|---|---|
history_dt_offset |
[1], [B] when batched |
ids = x_ids[:, 4].long() + history_dt_offset (batched: + history_dt_offset[batch]) |
It is -min(0, min emitted dt), so it is 0 when no history is supplied, and
the inverse is dt = ids - history_dt_offset. With two history steps on
blocks/smedium the raw column ranges over [-2, 0], history_dt_offset is
2, and the shifted ids range over [0, 2] — an embedding of size 4.
history_dt_offset is a tensor field, not metadata, so it survives
include_metadata=False.
The same offset shifts edge_attr[:, 7] and tuple_dt_ids (equivalently
tuple_attr_ids[:, 4]). On ObjectGraphEncoder and TransformerBiasEncoder
those are the only places the history age appears — x_ids[:, 4] stays at
[0, 0] there, so shifting it is a no-op. See
Objects-only facades.
Per-graph auxiliary fields
| Field | Shape | Present when | Meaning |
|---|---|---|---|
history_dt_offset |
[1] / [B] |
always | shift for column 4, above |
anchor_index |
[1] / [B] |
an anchor node was emitted | node index of the auxiliary <nullary> anchor (globally offset in a batch) |
has_anchor |
int metadata | include_metadata=True |
1 iff an anchor node was emitted |
instance_node_indices |
[M] |
instance tables are on | reified node index per instance row |
The anchor is one extra node, role anchor (id 6), appended as the last
node of the graph so no pre-existing index shifts. It is emitted exactly when
node_universe == "objects_only" or hyperedge incidence is on — i.e. for
ObjectGraphEncoder, TransformerBiasEncoder, and
HypergraphIncidenceEncoder. It stands in for the empty argument list: an
arity-0 instance hangs its nullary_self loop and its hyperedge membership
there. It is not an object — absent from object_names, never in
spd_* — so object-role pooling (x_ids[:, 0] == 0) already excludes it.
anchor_index is present exactly when an anchor is; the spec's -1 sentinel
is a single-graph convenience:
anchor = int(data.anchor_index[0]) if bool(getattr(data, "has_anchor", 0)) else -1
In a batch, anchor_index is [B] of global node indices and equals
ptr[1:] - 1, since the anchor is always its graph's last node.
instance_node_indices reports where each instance row was reified. In the
star universe that is a real node index for every row. In objects_only it is
-1 for everything except arity-0 rows (which point at the anchor) and action
rows (actions are reified in every universe). That -1 is not batch-safe:
the field increments by the node offset, so a -1 in graph k collates to
offset_k - 1. Mask by the instance itself rather than by sign — a row is
meaningful in objects_only exactly when its tuple slot is empty or its
tuple_role_ids entry is 5 (action).
Strategy extras
| Field | Shape | Emitted by |
|---|---|---|
hyperedge_index |
[2, sum(sizes)] — row 0 member node ids, row 1 hyperedge ids |
HypergraphIncidenceEncoder |
hyperedge_attr_ids |
[M, 6], same column order as x_ids |
HypergraphIncidenceEncoder |
num_hyperedges |
[1] / [B] |
HypergraphIncidenceEncoder |
tuple_args / tuple_sizes / tuple_ptr |
flattened argument node ids, per-row arity, CSR offsets derived from the sizes | TupleTensorEncoder, ObjectGraphEncoder, TransformerBiasEncoder |
tuple_rel_ids, tuple_role_ids, tuple_sign_ids, tuple_level_ids, tuple_dt_ids, tuple_category_ids |
[T] each |
same |
tuple_attr_ids |
[T, 6] — the six above stacked in x_ids column order (so column 1 is tuple_rel_ids + 1) |
same |
num_tuples |
[1] / [B] |
same |
spd_src / spd_dst / spd_dist |
[K] each |
TransformerBiasEncoder |
tuple_ptr is derived from tuple_sizes on every path, so
tuple_ptr.numel() - 1 == tuple_rel_ids.numel() holds after native batching
and after a manual Batch.from_data_list alike.
Directed by design. Derived graphs carry explicit reverse edges labeled
arg_bwd, clique_bwd, and so on rather than relying on conversion-time
mirroring: the schema flag include_reverse_edges disables mirroring for this
family, so converting single graphs and re-batching them by hand agrees
exactly with encode_batch_pyg. (Other families, such as ColorEncoder,
intentionally keep undirected mirroring.) line_share shortcuts honour the
same flag. Because the graph is directed, feed it to directed-capable layers
or rely on the explicit reverse edges for symmetric message passing.
Embedding Recipe
There is no data.x
x_ids is the only node-feature source these encoders emit. The carrier does
not define x at all, so data.x is None and
conv(data.x, data.edge_index) raises immediately on any stock layer
(AttributeError: 'NoneType' object has no attribute 'size' from GCNConv,
TypeError: 'NoneType' object is not subscriptable from GATv2Conv).
That is the intended behaviour, and it is a change. The carrier used to ship
an all-zero [N, 6] float x as a num_nodes placeholder, so the PyG reflex
conv(data.x, data.edge_index) ran, trained, and converged — on nothing. A
zero-filled feature matrix carries no information: on blocks/smedium, a
GCNConv over 13 nodes returns 1 distinct output row, identical for every
node, where the same layer over x_ids returns 10. The entire encoding was
discarded, silently, with no error and no warning. Since this family's contract
is that a loss must be explicit rather than silent, the placeholder is gone and
the reflex now fails loudly instead. Embed x_ids, as below.
num_nodes is set explicitly on the carrier, so nothing downstream depended on
x to size the graph; batching, ptr, and pooling are unaffected.
Embedding the channels
This is the recipe for the star-shaped facades — StarGraphEncoder,
AtomLineGraphEncoder, HypergraphIncidenceEncoder, TupleTensorEncoder —
whose x_ids rows carry real labels because every literal instance has a node.
For ObjectGraphEncoder and TransformerBiasEncoder, read
the next subsection first.
Embed each channel separately, concatenate, then feed any message-passing
layer. Take the edge-feature width from the tensor rather than hardcoding it —
it is 9 today and edge_channel_names is the authority:
import torch
import torch.nn as tnn
from torch_geometric.nn import GATv2Conv
data = encoder.encode_pyg(state) # DerivedGraphData
num_channels = data.x_ids.size(1)
HISTORY_DT = 4 # the one signed channel
columns = []
for c in range(num_channels):
ids = data.x_ids[:, c].long()
if c == HISTORY_DT:
ids = ids + data.history_dt_offset # shift the signed channel
embedding = tnn.Embedding(int(ids.max().item()) + 2, 8)
columns.append(embedding(ids))
feats = torch.cat(columns, dim=-1)
conv = GATv2Conv(feats.size(-1), 64, edge_dim=data.edge_attr.size(1))
out = conv(feats, data.edge_index, data.edge_attr.float())
# Read out over object-role rows only (role channel == 0).
# The anchor node has role 6, so this mask already excludes it.
object_mask = data.x_ids[:, 0] == 0
graph_embedding = out[object_mask].mean(dim=0)
In batch mode the shift is per graph:
ids = batch.x_ids[:, HISTORY_DT].long() + batch.history_dt_offset[batch.batch]
Sizing an embedding from int(ids.max()) + 2 is a convenience for one graph.
For a model that must accept every state of a problem, size from the
vocabularies instead: len(vocab_relations) + 1 for column 1,
len(vocab_roles) for column 0, len(vocab_categories) for column 5, and
your own bound on goal depth and history length for columns 3 and 4.
Layers without edge features (GCN/SAGE/GIN/PNA/...) simply ignore
edge_attr; layers with an edge_dim (GAT/GATv2/TransformerConv/NNConv/
CGConv) consume it as-is. For HypergraphIncidenceEncoder output, pass
hyperedge_index to torch_geometric.nn.HypergraphConv — with
use_attention=True, project hyperedge_attr_ids to in_channels first. For
TransformerBiasEncoder output, use spd_src / spd_dst / spd_dist to
build attention-bias terms over the clique-projected object nodes.
Objects-only facades: the content is on the edges
ObjectGraphEncoder and TransformerBiasEncoder reify no fact, goal, subgoal
or history node — that is the whole point of the objects-only universe — so
there is no node row for any of those labels to live on. Their x_ids is
consequently information-free: every object row is all zeros, the anchor
row is [6, 0, 0, 0, 0, 0], and no other row exists. Measured on
blocks/smedium:
| Facade | N |
distinct x_ids rows |
non-zero x_ids columns |
non-zero edge_attr columns |
|---|---|---|---|---|
StarGraphEncoder |
13 | 7 | 0, 1, 5 |
0, 1, 2, 3, 4, 8 |
ObjectGraphEncoder |
4 | 2 | 0 |
0, 1, 2, 3, 4, 8 |
TransformerBiasEncoder |
4 | 2 | 0 |
0, 1, 2, 3, 4, 8 |
Two distinct feature rows for the entire graph. Run the recipe above on that
and you get a near-constant node-feature matrix: three distinct rows out of
five even in the full-fidelity encoding with goals, subgoals, history and
actions supplied. Nothing is lost by the encoder — see
Information Content, both facades are lossless as
emitted — but a consumer that reads only x_ids throws all of it away.
Two consequences:
- You need an edge-conditioned layer.
GCNConv/SAGEConv/GIN/PNAignoreedge_attrentirely and will see nothing but topology. UseGATv2Conv,TransformerConv,NNConvorCGConvwithedge_dim=data.edge_attr.size(1), or consume the tuple instance table directly. history_dt_offsetapplies to the edges, not tox_ids. The signed history age never reachesx_ids[:, 4]in this universe: with two history steps onblocks/smediumthat column stays at[0, 0]whileedge_attr[:, 7]andtuple_dt_idsboth range over[-2, 0]andhistory_dt_offsetis2. Shift column 7 ofedge_attrandtuple_dt_ids(equivalentlytuple_attr_ids[:, 4]); shiftingx_ids[:, 4]here is a no-op.
An edge-conditioned pass, verified end to end on the full-fidelity
blocks/smedium encoding (5 nodes, 23 edges):
import torch
import torch.nn as tnn
from torch_geometric.nn import GATv2Conv
data = encoder.encode_pyg(state) # ObjectGraphEncoder / TransformerBiasEncoder
# x_ids carries only the role column here, so give each node a role embedding
# and let the edges carry the state content.
node_feats = tnn.Embedding(len(data.vocab_roles), 32)(data.x_ids[:, 0].long())
# Embed every edge channel. Column 7 is the signed one in edge_attr.
EDGE_HISTORY_DT = 7
edge_columns = []
for c in range(data.edge_attr.size(1)):
ids = data.edge_attr[:, c].long()
if c == EDGE_HISTORY_DT:
ids = ids + data.history_dt_offset
edge_columns.append(tnn.Embedding(int(ids.max().item()) + 2, 8)(ids))
edge_feats = torch.cat(edge_columns, dim=-1) # [E, 72]
conv = GATv2Conv(node_feats.size(-1), 64, edge_dim=edge_feats.size(-1))
out = conv(node_feats, data.edge_index, edge_feats) # [N, 64]
object_mask = data.x_ids[:, 0] == 0 # role 0; excludes the anchor (role 6)
graph_embedding = out[object_mask].mean(dim=0)
edge_attr has 19 distinct rows out of 23 on that encoding, so edge_feats
does too, and the layer returns 5 distinct output rows out of 5 — the state is
back. Contrast the x_ids-only recipe on the same graph: 3 distinct feature
rows out of 5, and none of the history, sign or goal-level information at all.
The alternative is to skip the topology and read the instance table, which
objects_only always emits. tuple_attr_ids is [T, 6] in x_ids column
order, so the same per-channel embedding applies, with the same shift on
column 4:
rows = data.tuple_attr_ids.long().clone()
rows[:, 4] += data.history_dt_offset # column 4 is the signed one here too
labels = torch.cat(
[tnn.Embedding(int(rows[:, c].max().item()) + 2, 8)(rows[:, c])
for c in range(rows.size(1))],
dim=-1,
) # [T, 48]
# Argument object node ids of instance i, in argument order:
# data.tuple_args[data.tuple_ptr[i]:data.tuple_ptr[i + 1]]
sizes = data.tuple_ptr[1:] - data.tuple_ptr[:-1]
row_of_arg = torch.repeat_interleave(torch.arange(sizes.numel()), sizes)
row_of_arg maps each entry of tuple_args to its instance, ready for a
scatter pool of whatever per-object representation you have. Note that
object nodes in this universe carry no features of their own — object identity
is positional, not featural — so pool out from the graph pass above, or your
own object embeddings, rather than the role embedding.
Invariants You Can Rely On
These hold for every facade, every backend, and every state of a problem.
- No empty hyperedges.
hyperedge_index[1].max() + 1 == hyperedge_attr_ids.size(0). An arity-0 instance takes the anchor as its single member, soHypergraphConv's inference ofnum_edges— which is exactlyhyperedge_index[1].max() + 1— always agrees with the attribute table. This previously failed: with(handempty)as the goal onblocks/smediumthe encoder records 9 instances, and dropping the anchor memberships (the old zero-member behaviour) makes PyG infer 8 against 9 attribute rows. - Every instance leaves a trace in every universe. Arity >= 2 gets its
projection or star edges, arity 1 a
unary_selfloop on its argument, arity 0 anullary_selfloop on the anchor. - Instances that differ in any channel produce different edge rows. Relation, role, sign, goal level, history age, and category all ride on columns 3..8, so a goal literal is never byte-identical to a state fact.
- The graph view is a set; the instance tables are multisets. Passing the
same literal twice yields one node and one set of edges, but two tuple rows
and two hyperedges. On
blocks/smedium,goals=[lit, lit]leaves the star view at 12 nodes / 23 edges while the tuple table goes from 9 rows to 10. - Node names are injective. Goal suffixes render
[g],[sg],[ssg],[sssg], then[sg4],[sg5], ... so the same atom at different subgoal levels never collides. - The anchor is not an object. Absent from
object_names, never inspd_*, always the last node. - Native batching equals manual re-batching.
encode_batch_pyg([...])agrees withBatch.from_data_list([enc(s) for s in ...])on every field, includinganchor_index,history_dt_offset,instance_node_indices,hyperedge_attr_ids, and thetuple_*vectors.
Information Content
Every derived encoder carries the full literal-instance content of the state.
The unit is the instance tuple
(role, relation_id, arguments, sign, goal_level, history_dt, category), and
the per-encoder verdicts, the exact recovery procedures, and the residual
losses are stated in
Derived Encoding Strategies § Information Content.
The short version:
- Star / line-graph views recover the instance set from
x_ids,edge_index, andedge_attralone. For each non-object, non-anchor node, channels 1..5 give the labels and its outgoingarg_fwd(oraction_fwd) edges give the arguments, sorted bypos_a. - Hypergraph and tuple views recover the instance multiset, arguments in order and repeats included.
- Objects-only views recover the multiset from the tuple table, which is
why
objects_onlyforces those channels on. The pairwise projection by itself cannot say which pairs of an arity >= 3 instance belong together. Note the reading order: nothing here is onx_ids, so a consumer must go toedge_attror the tuple table — Objects-only facades covers what that means for a model. Lossless as emitted is not the same as reachable through any recipe. include_metadata=Falsekeeps every tensor but drops the vocabularies, so ids can no longer be decoded to names.
Here is the star-view recovery, in full:
import collections
def instances(data):
"""Recover the literal-instance set from a star-shaped derived graph."""
x, ei, ea = data.x_ids.long(), data.edge_index, data.edge_attr.long()
args = collections.defaultdict(dict)
for e in range(ei.size(1)):
if int(ea[e, 0]) in (0, 9): # arg_fwd, action_fwd
args[int(ei[0, e])][int(ea[e, 1])] = int(ei[1, e])
out = []
for v in range(x.size(0)):
role = int(x[v, 0])
if role in (0, 6): # object, anchor
continue
slots = args.get(v, {})
out.append((
role,
int(x[v, 1]) - 1, # relation id, -1 == none
tuple(slots[k] for k in sorted(slots)),
int(x[v, 2]), int(x[v, 3]), int(x[v, 4]), int(x[v, 5]),
))
return collections.Counter(out)
On blocks/smedium with negated goals, two subgoal layers, two history steps,
one grounded action, and an (on a a) goal, this reproduces the encoder's own
tuple table exactly — 16 instances, argument order and repeats included.
Batching
Use encode_batch_pyg([...]); collation is handled natively and returns a
standard PyG Batch with batch / ptr vectors, so global_mean_pool and
friends work unchanged. Batch is the fast lane for encoding N states in one
call: one native batch assembly replaces N Python-level encodes, and
scripts/benchmark_derived_encoders.py prints a batch-vs-singles audit
(--problems large --batch-sizes 32,256). Typical advantage is 1.1-1.8x;
on the largest graphs with edge-heavy views (atom line graph at n=256) the
per-entry cost is on par with singles (~2 us/entry) while still saving the
N-1 call round-trips — repeated states are prepared once and reused.
batch = encoder.encode_batch_pyg([state_a, state_b])
out = conv(embed(batch.x_ids.long()).flatten(1), batch.edge_index)
graph_out = global_mean_pool(out, batch.batch)
Per-graph scalars stack rather than collapse: history_dt_offset and
anchor_index become [B] vectors, indexed with batch.batch (for the
former) or read positionally (for the latter). Node-index fields
(anchor_index, instance_node_indices, tuple_args, and row 0 of
hyperedge_index) carry node-offset increment rules; label fields
(hyperedge_attr_ids, every tuple_*_ids, history_dt_offset) do not
increment.
Shared vocabulary metadata is normalized back to single lists after batching.
If you re-batch singles manually (Batch.from_data_list([...])), PyG keeps
per-graph copies of those list and scalar attributes;
normalize_derived_graph_batch_metadata(batch) collapses them back to one
shared value — the vocabularies including vocab_relations / vocab_actions,
and the batch-invariant scalars node_universe, atom_expansion,
num_predicates, has_anchor and hyperedge_note.
The per-graph name lists are not shared and stay nested one level, so
node_names[k] and object_names[k] are graph k's own lists — on both the
native and the Batch.from_data_list path. A two-state batch of
blocks/smedium gives object_names == [['a', 'b', 'c'], ['a', 'b', 'c']]
either way, not one flattened list.
Streaming
Every facade provides .stream(), mirroring the ColorEncoder stream API:
stream = encoder.stream()
stream.append(state_a)
stream.append(state_b)
batch = stream.flush_pyg()
Backend Selection
Pymimir problems and pytyr planning tasks are auto-detected. Pass
backend="pymimir" or backend="pytyr" to override detection explicitly.
Outputs from different backends share the same channel contract and
vocabulary semantics.
Upgrading: What Changed Incompatibly
The losslessness work changed the carrier in ways that break code written against the previous contract:
| Was | Is now |
|---|---|
x is an all-zero [N, 6] float placeholder, so conv(data.x, ...) runs and silently returns a constant graph |
x is removed; data.x is None and stock layers raise. Embed x_ids |
edge_attr is [E, 3] |
edge_attr is [E, 9]; read the width from edge_attr.size(1) / edge_channel_names, and pass it as edge_dim |
channel_names[1] == "predicate_id_plus_one" |
channel_names[1] == "relation_id_plus_one" |
x_ids[:, 1] holds a predicate id for facts and an action-schema id for actions, in colliding spaces |
one unified relation space; action schemas are shifted by num_predicates |
hyperedge_role_ids, a [M] role vector |
hyperedge_attr_ids, an [M, 6] table with all six channels; hyperedge_role_ids is removed |
vocab_roles has 6 entries |
7 entries; anchor = 6 is appended (0..5 unchanged) |
vocab_edge_kinds has 12 entries |
13 entries; unary_self = 12 is appended (0..11 unchanged) |
vocab_categories has 3 entries |
4 entries; action = 3 is appended, and action nodes/edges/rows now report category 3 instead of 0 (static) |
objects_only materializes no auxiliary node |
one extra anchor node, always last; x_ids[:, 0] now contains role 6 |
objects_only may omit tuple channels |
objects_only always emits them |
| arity-0 hyperedges have zero members | they have the anchor as their single member, so M and PyG's inference agree |
line_share always emits both directions |
it honours include_reverse_edges |
| a repeated instance duplicates its graph edges | it does not; only the instance tables grow |
goal levels >= 3 all render [sssg] |
level L >= 4 renders [sg<L>], keeping node_names injective |
New graph attributes: vocab_relations, vocab_actions, num_predicates,
has_anchor. New fields: anchor_index, history_dt_offset,
instance_node_indices, tuple_sign_ids / tuple_level_ids /
tuple_dt_ids / tuple_category_ids, the stacked tuple_attr_ids, and the
counts num_tuples / num_hyperedges.
Compatibility Guarantee
tests/encoding/test_gnn_conformance.py is the executable proof of this
page's contract: every facade is fed through forward+backward passes of ten
stock PyG layers (plus HypergraphConv on the hypergraph output), including
the embedding path and pooled batch training. A runnable walkthrough lives in
examples/encoders/derived_graph_example.py.
Visualizing Derived Encodings
Every facade ships to_networkx(data), draw(data, ...), and
summarize(data) helpers that decode the integer channels back into names:
- Nodes are shaped and colored by role: blue circles are objects, orange
circles facts, green/red diamonds goals/subgoals, squares history/action
anchors, a hexagon the
<nullary>anchor, pink pentagons the auxiliary hyperedge anchors. - Edges are styled per kind: solid gray argument edges (reverse directions
are hidden by default since the forward edge already carries the position
label), colored projections for clique/chain/star-first views, dashed cyan
line_shareshortcuts, dotted pink memberships. include_hyperedges,include_reverse_edges,include_line_shares, andinclude_self_loopsonto_networkxcontrol exactly which structural pieces are materialized into the NetworkX graph;edge_labels=Trueondrawannotates each arrow with its kind and positions. Note that thenullary_selfandunary_selfloops that carry arity-0 and arity-1 instances are self-loops, soinclude_self_loops=Falsehides them — and with them the only trace some instances leave in an objects-only view.
data = encoder.encode_pyg(state)
encoder.draw(data) # matplotlib axes with legend
print(encoder.summarize(data)) # "roles: ... ; kinds: ..."
examples/encoders/derived_graph_example.py renders all five graph-shaped
strategies side by side into derived_graph_example.png.