onf-c2/docs/GLOSSARY.md

Glossary

Every term used in this repo, defined once. Grouped by concept, not alphabetised — terms that are easy to confuse sit next to each other on purpose.

---

Naming

ONF — the Python package name (src/onf), expanding to "Oriented Neural Field". Historical. The current method is not a neural field. Treat onf as an opaque package name.

cleanliness field — the one component that is still a field: a 136,216-parameter MLP mapping a joint configuration to a scalar distance-to-manifold. Stored as onf_head.npz. → technical/02 §2.1

---

The graph

node — one run of up to COARSEN = 5 consecutive raw frames from a single demonstration, cut short at any gripper state change so that every node has exactly one gripper state. long suite: 28,476 nodes over 500 demos. → technical/01 §1.2

raw frame — one timestep of the original LIBERO HDF5 trajectory. long suite: ~131,000 raw frames total, ~4.6 raw frames per node (below COARSEN because gripper flips force early cuts).

strand (owner, [V] i4) — which demonstration a node came from. 500 strands in long.

lane (task_id, [V] i2) — which task a node came from. 10 lanes in long. Strands nest inside lanes: 50 strands per lane.

phase ([V] f4) — position within an episode in raw-frame space: arange(T)/(T−1) evaluated at the node's first frame. 0.0 = first frame, 1.0 = last. Comparable across demos of different lengths. Used for binning, masking and cross-demo comparison.

t_frac ([V] f4) — position within an episode in node space: t_idx / (n_nodes_in_demo − 1). Fed to the network through psi(t_frac).

phase and t_frac are both in [0,1] and both mean "how far along". They are not interchangeable. They differ because coarsening is not uniform. Using one where the other is meant selects the wrong nodes with no error raised. → technical/01 §1.3, "Easy to get wrong"

phase bin — one of NBINS_ALIGN = 20 equal buckets over phase ∈ [0,1]. The single bucketing every phase histogram in the subsystem agrees on (onf/graph/core/binning.py).

phase_conv — a string stamped into g_nodes.npz recording which phase convention produced it ("arange(T)/(T-1) full"). Re-checked on load; a mismatch raises.

relation — one of the R = 12 edge types. The GNN embeds relation types, not nodes, so a relation that happens to be empty in some graph is legal and must still run.

dilation — the hop length of a next/prev relation, in node steps: DILATIONS = (1,2,4,8,16). Load-bearing: with next1 only, 3 message-passing layers reach 3 nodes ≈ 15 raw frames, while a pre-grasp approach spans ~80 raw frames.

sibling — kNN edge to a different demo, same task, same gripper state. Out-degree K_SIBLING = 8. Relation index 10.

align — kNN edge to a different task, same phase bin, same gripper state. Out-degree K_ALIGN = 4. Relation index 11.

stage ([V] i2) — cumulative count of gripper releases along a demo. Diagnostic only. Nothing in edge construction, training or retrieval reads it, and there is deliberately no stage relation. → technical/01 §1.5

log_idf ([V] f4) — an additive prior on the output logit, computed from sibling degree (GFM-RAG eq. 15–16). Stored in g_edges.npz.

graph_hash — a hash of the (g_nodes, g_edges) pair, stamped into g_head.npz and g_track.npz. Node ids are positional and meaningless across builds, so a head loaded against a foreign graph returns confident, correctly-shaped logits on the wrong strands. The hash check is the only thing that catches this. → technical/05

---

Two heads, similar filenames, different models

	g_head.npz	onf_head.npz
what	the GNN retrieval head	the cleanliness field
input	a window of 8 joint states [8,7]	one joint config [7]
output	a distribution over all 28,476 nodes	one scalar
trained by	onf.graph.train	onf.field.train
params	independent of |V| (inductive)	136,216
read by	GraphRetriever, GraphTracker	ONFField.f_value → query pooling weights

These are two different models in two different files. g_head scores nodes. onf_head scores how much to trust each frame of the query.

---

Query and retrieval

query (Q) — a window of HIST_H = 8 consecutive joint states, plus their finite-differenced velocities and gripper flags. HIST_H equals one policy action chunk.

cleanliness weight (w, [8]) — sigmoid(−f(q_i)) where f is the cleanliness field. Pooled through softmax(log w), not w / sum(w), so that w_i == 0 gives a hard zero rather than 0/0.

seed set — the SEED_TOPK = 256 nodes given non-zero initial state h0. Everything outside the seed set starts at exactly zero, preserving the NBFNet semantics of "representation of v conditioned on a seeded source set".

reachability — whether message passing ever delivered a message to a node from a seeded source. Tracked explicitly, not inferred from h == 0 (layer_norm can zero a reached node's state). Unreached nodes get logit −inf.

abstain — a scalar logit produced by a separate head, compared against logits[reached].max(). Trained on the same comparison performed at deploy time, with the node term detached so it never drags the ranking logits.

entry stratum — the mask applied when GR_ENTRY_BAND > 0: task lane ∩ phase ≤ band (0.05) ∩ reachable, with the current demo's own strand excluded (leave-one-demo-out). ~229 of 28,476 nodes on the long graph.

move cost — ‖q_node − q_now‖, passed as the third input to the readout MLP instead of being applied as a hand-written argmin. The network learns how much to penalise motion, including accepting a longer move when it is more confident.

---

Training

pretext task — given a window ending at raw frame T, predict the node at T + ADVANCE (0 raw frames, i.e. the window's own end) on the same demo. Requires traversal, not lookup: the window is a trajectory, and the transition kernel — not the head — owns how far forward to look.

TRAVERSAL / ENTRY / ENTRY_STATIC / DRIFT — the four query classes drawn by make_queries. ENTRY_STATIC (share 0.15) produces repeat(q0, 8) — velocity identically zero — because that is the exact input shape a settled arm produces at deploy time and no other class generates it. DRIFT (share 0.15) is the only class with a clean-to-perturbed breakpoint inside the window; every other class is uniformly clean or uniformly perturbed, so none of them poses the question of which rows of a history are still trustworthy. → technical/02 §2.4

provenance vs consequence — is_clean records which branch generated a query. abstain_is_correct records whether abstaining is the right behaviour for it. An ENTRY sample with a tiny perturbation is still on-support, so the loss label uses consequence, not provenance.

INTER_DEMO_SPACING — the median leave-one-demo-out nearest-neighbour distance between nodes: "how far apart independent demos usually sit". Measured, not chosen — ~0.054 rad on the long graph.

LODO — leave-one-demo-out. Used for the perturbation floor, INTER_DEMO_SPACING, and the basin geometry quantiles.

hard negative — a mined distractor, N_NEG = 16 per query across three buckets: same t_idx different strand; near in q but far in phase (self-intersection, ~4.1% of frames); and the query's own nearest neighbour when it is not the answer.

---

Sentinel (t > 0)

belief (b_t, [V]) — a distribution over graph nodes maintained across checks. b_t ∝ [(1 − ε)·P·b_{t−1} + ε·L_t] · L_t.

check — one sentinel evaluation, every SN_CHUNK = 8 env steps (one policy action chunk), over a window whose rows are SN_GRAPH_STRIDE = 1 env step apart. A check advances ~1.65 nodes at ~4.85 raw frames per node.

transition kernel (P) — [(1−β)I + β·M_sib] · Σ_a π_a S_a. Sibling-mix laterally, then push forward along the advance mixture. Built from TRACK_KERNEL_RELATIONS = next1..next16 + sibling; align and all prev relations are excluded on purpose.

advance set — TRACK_ADVANCE_SET = (0,1,2,4,6,8,12,16) raw frames. Mixed over, not point-estimated, because a check advances a fractional number of nodes and rollouts run slower than demos. a = 0 (the stall self-loop) is mandatory.

leak (ε) — the restart weight. Restarts toward the current observation L_t, not toward uniform. A uniform restart puts mass on impossible phases and discards the aliasing suppression the filter exists to buy.

basin — the certified region around a node, fitted per (task, phase-bin) from held-out clean demo replays: radius r = p95 and KDE bandwidth h = p50 of LODO nearest-neighbour distances.

r_eff — max(r − h, 0). The sentinel target is q* = q_now + max(0, 1 − r_eff/‖q_b − q_now‖)·(q_b − q_now): exactly q_now when already inside, otherwise the point on the segment at distance r_eff from the anchor. Undoes drift down to the boundary and stops.

---

The blend

tracking chunk (a_track, [K, 6]) — the reference segment restated in the policy's own action units. Row 0 is measured against the LIVE pose (feedback), row k against ee_ref[k-1] (feedforward). → technical/03 §3.2

action scale — metres per action unit for dims 0:3 and radians per action unit for dims 3:6, fitted off the demos into action_scale.json. Two scalars, not one: they differ by 8.8×. Rotation is composed in the world frame, never subtracted.

blend — a_exec[:, 0:6] = (1−α)·a_policy + α·a_track, applied once per chunk at the refill line. Dim 6, the gripper, passes through untouched — the command is binary.

alpha (α) — the blend weight. Either a fixed scalar (SN_BLEND_ALPHA) or, under SN_BLEND_LEARNED, a [K, 6] array from AlphaNet: one weight per chunk row and per pose block.

SN_BLEND_SCALE — a multiplier on the learned alpha. The chunk-MSE objective fits the right per-check shape at too confident a level, so the head is rescaled onto the average authority a fixed weight was measured to work at. Derived per head, not swept. → technical/03 §3.6

bound / ACTION_LIMIT — the row-0 saturation, bound·tanh(row0/bound), at 1.0 action unit. Row 0 is an unbounded pose error and the simulator clips actions to [-1, 1]; this is the deleted servo's gain limit restated in action space. A constant, not a learned parameter — the one run that learned it drove it to 24.5.

corrupted retrieval — a training row given a deliberately wrong retrieval (WRONG_TASK, OFFSET, WRONG_PHASE) with the regression target left correct. The only rows on which alpha's gradient can point down. → technical/03 §3.7

---

Evaluation

base — the frozen policy, untouched. The only definition of a mode is evals/common/modes.sh; both benchmark drivers parse that file so the recipes cannot drift apart. The other modes are blend (alpha 0, a plumbing check), a family of fixed-alpha probes (blend_a05, blend_a015, blend_bounded, blend_a015_bounded, …) and the learned-weight arms (blend_scaled015, blend_full). blend_full is the current recipe.

suite — one of object, spatial, goal, long. Maps to a LIBERO dataset directory (long → libero_10, not libero_long).

axis — one perturbation axis in LIBERO-Plus: Robot_Initial_States, Light_Conditions, Background_Textures, Sensor_Noise, Language_Instructions, Objects_Layout, Camera_Viewpoints.

cell — one (suite × axis × mode × policy) result.

rung — one step of the eval ladder in configs/sr_ladder.yaml. R1 is the 24-episode smoke test.

churn — the fraction of episodes that flip outcome between two identical runs. GR00T-N1.7 is flow-matching and unseeded: ~11.2% churn. StableVLA: 0 churn measured over 393 episodes.

dead artifact — written to disk but read by nothing: q_manifold.npz, q_manifold_full.npz. Verified by grepping np.load across src/, tests/, scripts/, evals/.

---

Constants quick reference

Full table with CHOSEN / DERIVED provenance: technical/06-config-reference.md.

constant	value	where
COARSEN	5 raw frames per node	graph build
DILATIONS	(1,2,4,8,16) node steps	graph build
K_SIBLING / K_ALIGN	8 / 4	graph build
NBINS_ALIGN	20 phase bins	everywhere
KERNEL_BW	0.15 rad	Gaussian edge-weight default; INIT of the learned seed sigma
HIST_H / SEG_K	8 / 8	one policy action chunk
SEED_TOPK	256 nodes	seeding
LAYERS	3, weights shared	GNN
GR_ENTRY_BAND	0.05 phase	entry stratum mask
SN_CHUNK	8 env steps	sentinel check spacing
SN_GRAPH_STRIDE	1 env step	sentinel window row spacing