Sparse Atom-Composition Encoding
mifrost.encoders.sparse_atom is a pure-Python (Stage 1: no native engine
involved) encoder for the sparse atom-composition architecture described in
"Sparse Atom Compositions for Relational STRIPS Message Passing". It stores
one persistent vector per argument occurrence of a represented atom, rather
than one vector per object, and exposes sparse pair/witness indices so a
consumer model can compose atoms that share an object pair without
materializing the dense object-pair universe.
The consumer is relmo.models.SparseAtomCompositionGNN (in the sibling
relm repository); SparseAtomCompositionEncoder produces its exact input
contract, SparseAtomCompositionBatch. mifrost.encoders.sparse_atom.validate_sparse_atom_composition
is a standalone reimplementation of every invariant that consumer's
prepare() checks, usable without constructing a model.
The contract, at a glance
| Field | Shape | Meaning |
|---|---|---|
atom_args, atom_offsets |
[I], [Q+1] |
Packed ordered atom argument tuples (CSR) |
atom_predicate_ids |
[Q] |
Emitted predicate id -- meaning depends on status_encoding (see below) |
atom_channel_ids |
[Q] |
One of the four frozen channels in "channel" status encoding; always 0 in "vocabulary" |
atom_batch, object_batch |
[Q], [O] |
Graph id per atom / per object |
pair_objects |
[P, 2] |
Ordered, non-diagonal, deduplicated object pairs |
pair_support_offsets/atom_ids/i/j |
CSR over [S] |
Every (atom, i, j) contributing to a pair |
composition_triplets |
[K, 3] |
(target_pair, left_pair, right_pair) witness rows |
atom_pair_ids, atom_pair_occurrence_i/j |
[M] |
Atom-to-pair maps, in global occurrence indices |
goal_available |
[B] |
Per-graph zeta flag |
object_carrier_occurrence_ids |
[O] |
One object(o) carrier occurrence per object, ordered by object id |
counterpart_occurrence_ids |
[I], optional |
R11 exact-tuple exchange, -1 where none |
object_type_ids |
[O], optional |
R13 per-object declared PDDL type id; None when the backend cannot resolve types |
Q = atoms, I = occurrences (sum(arity)), O = objects, P = pairs,
S = pair-support entries, K = witness triplets, M = atom-pair mappings,
B = graphs in the batch. Everything is a plain torch.long/torch.bool
tensor; SparseAtomCompositionEncoding (the encoder's carrier dataclass) has
exactly these attribute names, so it can be passed directly to
SparseAtomCompositionGNN(...).
Predicate arities aren't carried on the tensor contract at all: they are a
model constructor argument (predicate_arities=...), fixed once from
SparseAtomCompositionEncoder.schema (a SparseAtomPredicateSchema) at
construction time, shared by every graph the encoder ever produces. The same
goes for the reported channel cardinality (num_channels) -- see
Status encoding below.
Channel convention
Frozen, do not renumber:
| id | name | meaning |
|---|---|---|
| 0 | state |
current true atom (includes static facts, and every object(o) carrier) |
| 1 | satisfied |
supplied goal atom that is currently true |
| 2 | unsatisfied |
supplied goal atom that is currently false |
| 3 | auxiliary |
encoding artefacts that are not themselves facts (only the nullary star's carrier) |
In "channel" status encoding, the consumer allocates one wide atom MLP per
(channel, base_predicate) pair, so atom_predicate_ids must be the
base predicate id, not a channel-qualified relation id: on[state],
on[sat] and on[unsat] all share predicate id on, differing only in
atom_channel_ids. This is what lets the architecture's M_state,on,
M_sat,on, M_unsat,on split exist without tripling the predicate
vocabulary. In "vocabulary" status encoding these four rows fold into the
predicate vocabulary instead -- see below.
Why plain is off
The native flat-encoder family's GoalDerivation enum has five values
(plain, satisfied, unsatisfied, added_satisfied,
added_unsatisfied), and its library default is {plain, satisfied} --
every goal gets one plain atom, and satisfied goals additionally get a
satisfied atom, but there is no unsatisfied atom at all. That
default is a different encoding, tuned for a different architecture. This
encoder never emits plain: every supplied goal atom p(o) in the goal
conjunction G becomes exactly one status atom, satisfied xor
unsatisfied, depending on whether p(o) is already a member of the
current true-atom set S:
Atoms_goal(S, G) =
{ p_satisfied(o) : p(o) in G and p(o) in S }
U { p_unsatisfied(o) : p(o) in G and p(o) not in S }
Using the library default here would silently produce a plain goal atom
for every goal and no unsatisfied atoms at all -- voiding the two-tower
Blocksworld separation the architecture relies on (on_satisfied/
on_unsatisfied needs both a satisfied and an unsatisfied label to exist
for the separation argument to apply). tests/encoding/test_sparse_atom_composition.py::test_goal_status_split_exactly_one_atom_per_goal
asserts this directly: goal-derived channels are always a subset of
{satisfied, unsatisfied} and their count always equals the number of
supplied goal atoms -- never zero, never doubled.
A satisfied goal keeps its current-fact representation too: q(o) being
both true and a goal produces two atoms (one state, one satisfied),
not one atom carrying both roles.
Per-object carriers (R4)
Every object needs a persistent unary "carrier" atom so object_readout
and the exact-tuple exchange have somewhere to attach an object-level
representation even when an object appears in no other atom. That carrier
relation is the backend's own object predicate -- not an invented one.
Real PDDL backends already expose it: on blocks:small, StateView(problem).predicates
includes PredicateInfo(name='object', arity=1, category='static'), and
static_facts is exactly [Atom('object', ('a',)), Atom('object', ('b',))]
-- one object(o) static fact per domain object, already part of the
current-atom set S. There is no name collision to design around: the
object relation the backend exposes is the carrier relation the
architecture note writes as object^aux(o), so build_predicate_schema
reuses it (appending it, with encoded arity 1, only if a hand-built schema
omits it) instead of minting a second, reserved-looking predicate.
Because object(o) is a genuine static fact, its carrier occurrence lives in
the state channel, as part of the current atoms S -- not a separate
auxiliary channel. object_carrier_occurrence_ids[o] points at that
occurrence, one per object, ordered by object id (the consumer asserts this
ordering).
Fallback. If a domain or backend does not supply object(o) for every
object -- a hand-built test schema, or a future backend with gaps -- the
missing carriers are synthesized, still in the state channel, decided
per object rather than per domain: whatever is missing gets synthesized,
so an isolated object with no other atom mentioning it still gets a carrier.
On the two real Blocksworld fixtures exercised by
tests/encoding/test_sparse_atom_composition_relmo_integration.py, this
fallback path is never taken -- both backends already cover every object --
so it is verified there via hand-built Atom lists instead
(tests/encoding/test_sparse_atom_composition.py::test_missing_object_carrier_is_synthesized_per_object).
The one object that never gets a real object(o) fact is the distinguished
nullary object star (see Nullary normalization
below): it is not a real PDDL object, so no backend ever emits
object(star). Its carrier is therefore always synthesized, and it stays in
the auxiliary channel, since it is an encoding artefact rather than a
true fact -- the only auxiliary-channel atom this encoder ever emits.
Nullary normalization
A nullary atom such as handempty() has no argument to attach a persistent
occurrence vector to. This encoder ports the native hetero family's
nullary_object_name/add_nullary_predicates approach rather than the flat
family's ignore_zero_arity_relations=True default, which would silently
drop handempty instead of representing it: every nullary atom becomes a
unary atom on a distinguished auxiliary object,
mifrost.encoders.sparse_atom.NULLARY_OBJECT_NAME
("![nullary_symbol]!", the same literal the hetero family already uses).
The star object:
- is added to a graph's object universe only when that graph actually contains a nullary atom (a state with no nullary predicates never carries a dangling unused star);
- always gets a synthesized
object(star)carrier in the auxiliary channel (see Per-object carriers above); - participates in pairs and witnesses like any other object once it appears in a non-nullary atom's arguments too (it never does on its own, since every atom mentioning it is now unary).
No arity-0 atom is ever emitted by this encoder. The consumer's own
prepare() rejects arity 0 outright, naming this normalization in its error
message, and validate_sparse_atom_composition checks the same invariant
standalone.
Status encoding: channel vs. vocabulary
build_predicate_schema (and SparseAtomCompositionEncoder) take a
status_encoding argument with two values, matching the two ways the
architecture document's baseline comparison represents goal status:
"channel"(default): as described above --atom_predicate_idsis the base predicate,atom_channel_idsdistinguishes state/satisfied/unsatisfied/auxiliary, and the schema reportsnum_channels == 4."vocabulary": there is no status channel at all. Every(base predicate, channel)pair gets its own vocabulary entry instead -- the schema is four times as large --atom_channel_idsis always0, andnum_channels == 1. This is howrelmo.models.FlatRelationalGNNrepresents goal status: it extends the relation vocabulary with separate relations (P, orP_sat/P_unsat) rather than carrying a status channel. Vocabulary-mode names reuse the flat native encoder family's ownRelationKeybracket convention (seesrc/_core/mifrost/core/encoders/common/relation_key.cpp):on[state],on[sat],on[unsat],on[g](the last for the auxiliary channel, which has no flat-family analogue of its own).
Both modes encode exactly the same atoms and sparse topology --
pair_objects, composition_triplets, atom_pair_ids,
object_carrier_occurrence_ids, everything -- only the predicate/channel
labelling differs; atom_predicate_ids is precisely
schema.relation_id(base_predicate_id, channel) applied pointwise to the
channel-mode ids. This is what makes vocabulary mode useful: it is what the
architecture document's "identical input encodings across architectures
within each comparison" requirement needs for a like-for-like comparison
against FlatRelationalGNN, since both models can then be sized from the
same predicate vocabulary (predicate_arities, num_channels).
That equivalence has one asymmetry worth knowing before benchmarking with
it: SparseAtomCompositionGNN's join_sharing ablation derives a per-pair
join-template key from atom_channel_ids in prepare() (a pair keys on its
support channel when that support is channel-homogeneous, and on a
distinguished "mixed" key otherwise). In "vocabulary" status encoding every
atom's channel is 0, so every pair collapses onto the same template --
correct, not a bug, since the status distinction already lives in the
predicate id there, but it means the join-sharing ablation is only
meaningful in "channel" status encoding. Use "vocabulary" for a
like-for-like vocabulary comparison against FlatRelationalGNN; use
"channel" when the join-sharing ablation itself is what is being studied.
Pairs and witnesses (R7/R8/R9)
For distinct objects u, v, pair_objects holds every ordered pair with
at least one supporting occurrence -- (u, v) and (v, u) are independent
records, and both arise automatically from any single atom that mentions
u and v at two different argument positions (the position loop is over
all ordered (i, j), not just i < j). composition_triplets is built by
listing every triangle of the resulting undirected support graph exactly
once via degeneracy ordering (O(alpha * M), the same construction
relmo's own topology-stats triangle counter uses) and expanding each into
its 6 ordered (target, left, right) rows. atom_pair_ids /
atom_pair_occurrence_i / atom_pair_occurrence_j are the atom-to-pair maps
D+AGGR^args needs to distribute pair/composition information back to
occurrence stores; occurrence indices there are always global
(atom_offsets[q] + position]), never atom-local.
Batching (R12)
batch_sparse_atom_encodings concatenates a list of single-graph (or
already-batched) encodings into one, explicitly rebasing every index space
by that graph's own running totals before concatenating -- objects, atoms,
occurrences, pairs, and pair-support entries each get their own running
offset. No pair or witness triplet can span two input graphs: pair_objects
only ever references two objects with equal object_batch entries, by
construction (each graph's own pair_objects already only references its
own objects, and rebasing preserves that).
Object types (R13)
The architecture's per-occurrence side information s_{q,j} includes
argument object types, and the consumer carrier (object_type_ids) has a
slot for them. Whether a backend can supply them turned out to be
asymmetric, not a uniformly unfinished feature:
- pymimir: yes. The installed pymimir wrapper's
Object(andType) exposeget_bases()in addition toget_index/get_name-- contradicting an earlier assumption recorded in this codebase that only the latter two existed.Object.get_bases()returns the object's own declared type(s), andDomain.get_types()always includes the implicit PDDL root type"object", even for domains with no:typessection at all (verified against every fixture underdata/pddl/). - pytyr: no, genuinely. The
pytyr.formalism.planningtaskStateViewwraps is a translated representation, and PDDL types are compiled away before it exists: itsDomainhas noget_types(), and itsObject/Typereally do expose onlyget_index/get_name-- confirmed at the C++ layer, not just the binding surface.tyr::formalism::planning ::Object'sDatastruct (pytyr's ownnative/include/tyr/formalism/object_data.hpp) stores onlyindexandname, nothing else. The type hierarchy does exist earlier, on the raw parsed AST (pypddl.formalism.Task.get_objects()[i].get_types(), withType.get_bases()walking the full ancestor chain there), but thePlanningTaskthis reader is built from keeps no reference back to that AST or to the original PDDL file paths needed to re-parse it. This is a capability gap in what the translated task carries, not a missing binding to add.
SparseAtomCompositionEncoder/encode_sparse_atom_facts populate
object_type_ids whenever StateView.object_types is available and leave
it None otherwise -- never a fabricated constant that would silently
present as "every object has the same type." Ids come from a fixed,
domain-scoped vocabulary (SparseAtomTypeSchema, built by
build_type_schema from StateView.type_names), the same stability
guarantee build_predicate_schema already gives predicate ids: two
problems of one domain that happen to instantiate different subsets of its
declared types still agree on which type gets which id.
object_type_ids carries only the most specific declared type; the
hierarchy travels beside it. The per-object field stays a categorical id,
matching its consumer (SparseAtomCompositionGNN.object_type_embedding, a
single nn.Embedding lookup), and the most specific type is the most
informative single label a PDDL declaration gives (a truck implies
locatable implies object, never the reverse).
The hierarchy itself is domain schema, not per-object data, so it is
carried once as direct parent edges (DomainSnapshot.type_bases,
StateView.type_bases) and closed into
SparseAtomTypeSchema.ancestor_matrix -- a square 0/1 matrix over the type
vocabulary, exposed as SparseAtomCompositionEncoder.type_ancestors. The
closure lives at the schema because that is where type ids are assigned,
and the matrix has to be indexed by them. Its diagonal is always set: the
consumer reparametrises its table as A @ E, and the diagonal is what
leaves every type a free row of its own, so a zero there would remove
capacity rather than merely change a prior. A backend that reports type
names but no hierarchy yields the identity, which reproduces the leaf-only
encoding exactly.
Whether that reparametrisation earns anything is domain-dependent, and
mostly it does not: untyped domains encode types as unary predicates
instead, flat hierarchies contribute nothing, and most typed domains
(spanner, barman, delivery, transport) branch exactly at their predicate
slots, where the shared row is constant within a role and absorbed by the
consumer's role-conditioned map. Logistics is the clear exception --
locatable -> {package, vehicle -> {truck, airplane}} is three deep, so at
at's first argument the vehicle row genuinely separates vehicles from
packages.
An object declared with a PDDL either type (more than one base) has no
single "the" type, so pymimir's snapshot layer raises ValueError for it
rather than guessing -- no domain under data/pddl/ exercises this today.
The ancestor matrix does not change that: it is indexed by leaf id, so an
either object still has no id to look up.
Untyped domains degrade to a single real type id, not an absent field.
Because pymimir always resolves at least the implicit root type "object"
for every object -- typed domain or not -- object_type_ids being present
reflects "this backend can classify objects", not "this domain declares
more than one type". A Blocksworld problem therefore gets a real (constant,
all-zero) object_type_ids with num_object_types == 1, computationally
identical to leaving the field None (the consumer's own fallback is also
"treat every object as type 0"), but explicit rather than silent about why.
The synthetic nullary "star" object (see
Nullary normalization above) follows the same
logic from the other direction: it is not a real PDDL object, so rather
than leave it without a type (every id in the schema must be a genuine,
resolvable row) it is typed generically as the schema's root entry,
mifrost.encoders.sparse_atom.ROOT_TYPE_NAME ("object" -- the same
literal as OBJECT_PREDICATE, not by coincidence: pymimir reports it as
the real root of every domain's type hierarchy, the same way it reports
object as a real static predicate for the R4 carrier).
build_type_schema always guarantees this entry, synthesizing it if the
supplied type names omit it -- mirroring how build_predicate_schema
always guarantees OBJECT_PREDICATE.
Batching (batch_sparse_atom_encodings) concatenates object_type_ids
without index offsetting: it is a domain-scoped categorical value,
like atom_predicate_ids, not a per-graph local index like atom_args or
pair_objects (compare kEntityRoleIdsField -- GraphFieldMode::CAT with
no inc -- against kObjectIndicesField's GraphFieldMode::CAT plus
GraphFieldInc::Kind::NODE_OFFSET, in
src/_core/mifrost/core/encoders/flat/flat_encoder_common.cpp, which draws
exactly this distinction for the native flat-encoder family). It must be
present on every encoding in a batch or none: unlike
counterpart_occurrence_ids (whose -1 filler the consumer explicitly
treats as "no counterpart"), every id in [0, num_object_types) is a
genuine declared type, so there is no spare sentinel value for a graph with
no types once others in the batch declare real ones -- mixing them raises.
occurrence_type_ids -- a different, still-unaddressed R13 component (a
per-argument-position type drawn from the predicate/action signature,
rather than a per-object type) -- remains out of scope and stays None.
Backend-free core vs. the StateView facade
Two layers are exposed:
encode_sparse_atom_facts/batch_sparse_atom_encodings/build_predicate_schemaoperate on plain(predicate, args)tuples (mifrost.encoders.custom.state_view.Atom) and never touch pymimir or pytyr. This is what most oftests/encoding/test_sparse_atom_composition.pyexercises directly -- hand-built Blocksworld-style and synthetic-graph scenarios (six-cycle vs. two triangles, the two-tower goal-witness separation, and so on) without needing a PDDL problem at all.SparseAtomCompositionEncoderis a thinStateViewfacade over a real pymimir/pytyr problem. Itsgoals=parameter deliberately differs fromCustomGraphEncoder's lane convention:goals=Nonemeans goal-free (zeta=0) here, not "use the problem's own goal" -- this encoder has a genuine goal-free mode, and reusing the other convention would make it unreachable. Passgoals=encoder.view.goal_literals(state)explicitly for the problem's own goal, orgoals=()for a supplied-empty goal (zeta=1,G=∅; the same atom set as goal-free, differing only ingoal_available).