Topology vs Feature Geometry: Two Spaces Every Tensor Graph Lives In

When we say a graph "has geometry," we are usually being ambiguous, because a tensor-valued graph carries two different geometries that are easy to conflate. The first is topological: which nodes are connected, how far apart they are along edges, what the neighbourhood of a node looks like. The second is feature geometry: the internal layout of each node's tensor — the rows and columns of a [C, H, W] feature map, where "nearby" means spatially adjacent pixels, not graph neighbours. TGraphX is unusual among graph frameworks in keeping both geometries explicit, and understanding the distinction sharpens how you reason about what a tensor GNN can and cannot learn.

If you have read why flat vectors are insufficient, this article gives the geometric vocabulary behind that argument.

Two spaces, two distance notions

Fix a graph G = (V, E). The topology defines a discrete metric on the node set: the geodesic distance d_G(i, j) is the number of edges on the shortest path between nodes i and j. Neighbourhoods, k-hop balls, connected components, and motifs are all properties of this space. It is combinatorial and permutation-equivariant — relabel the nodes and the topology is unchanged up to that relabelling.

Now look inside a single node whose feature is X_i ∈ ℝ^{C×H×W}. The axes H and W index a continuous grid with its own notion of adjacency: pixel (h, w) is next to (h+1, w). The relevant metric here is the ordinary grid distance on {1,…,H} × {1,…,W}, and the symmetries that matter are translations and local correlations — the same structure that makes convolutions effective. This space has nothing to do with the graph's edges; it is the geometry of the signal each node carries.

The last row is the crux. Flattening X_i to a [C·H·W] vector destroys the feature geometry while leaving the topology intact. A standard GNN then operates on a graph that still has perfectly good topology but whose nodes have been geometrically lobotomised. TGraphX's design choice is to refuse that flattening.

How message passing couples the two

The two geometries are not independent during learning — message passing is exactly the operator that lets topology move information through feature space. Recall the decomposition covered in Inside Tensor Message Passing:

M_{i→j} = φ( X_i , X_j , E_{i→j} )
        A_j     = AGG_{ i ∈ N(j) }  M_{i→j}
        X'_j    = ψ( X_j , A_j )
        

Read it geometrically. The neighbourhood N(j) is a topological object — it is decided entirely by the edge set. The functions φ and ψ, when implemented as 1×1 convolutions in ConvMessagePassing, are feature-geometry operators — they transform the [C, H, W] content while preserving the spatial grid. So one hop of message passing says: gather the feature maps of my graph-neighbours, transform them in their own spatial geometry, and fuse them into mine. Topology chooses the participants; feature geometry governs the arithmetic.

This separation is also why permutation-equivariance and translation-structure can coexist. Aggregation over N(j) is invariant to the order of neighbours (a topological symmetry), while the convolutional message respects spatial layout (a feature-geometry symmetry). Neither symmetry interferes with the other.

Where each geometry lives in the source

The split is visible in the data structure. In tgraphx/core/graph.py, topology is the edge_index tensor of shape [2, E], and feature geometry is reported by the feature_shape property — the trailing shape of node_features. They are stored separately and validated separately.

Operators that act purely on topology live in tgraphx/algorithms (with connectivity, structural, and traversal modules covering BFS/DFS, shortest paths, and structural queries) and in tgraphx/mining (for example graph_summary and degree_statistics). These are classical graph computations and do not touch the node tensors at all — they are the topological half of the toolbox, comparable in spirit to what NetworkX provides. The feature-geometry half lives in the layers package, where the convolutional and attention message functions operate. Keeping them in different modules is not an accident; it mirrors the conceptual split.

Honest boundaries

It would be an overstatement to say TGraphX "unifies" the two geometries into a single new theory. It does something more modest and more useful: it declines to collapse them. The package still relies on standard combinatorial algorithms for the topological side and on standard convolutional operators for the feature side. What it adds is a data model and a set of layers that let both live in the same Graph object and the same forward pass, so a practitioner does not have to choose between relational reasoning and spatial reasoning. Whether that combination helps on a given dataset is an empirical question to be measured, not assumed.

Related guides

• Why Flat Vector Node Features Are Insufficient for Some GNNs
• Inside Tensor Message Passing: The φ → AGG → ψ Pipeline
• Graph Mining and Motif Discovery in TGraphX

Conclusion

A tensor graph is a discrete topology whose nodes each carry a continuous feature geometry. Flattening preserves the first and discards the second; TGraphX preserves both and lets message passing couple them, with topology choosing neighbourhoods and feature-geometry operators transforming content. Holding the two spaces apart in your head — and noticing that the source code holds them apart too, in edge_index versus feature_shape — is the cleanest mental model for tensor-aware graph learning.