Module community 

Topological semantic zoom — community detection → meta-nodes → fracture (#3).

Zooming out of a large graph should consolidate, not shrink-to-illegible. We detect the graph’s communities (densely-connected clusters) with Louvain modularity optimisation, then drive a zoom-aware collapse: at low zoom each community becomes one consolidated meta-node; as the user zooms in past a threshold the meta-node fractures open — its members ease out from the meta-centroid to their real positions under an injected-clock easing curve (the same dependency-injected easing seam facett-helix uses), so the structure blooms apart instead of popping.

What lands here vs the roadmap

This is one solid level of Louvain (local-moving modularity ascent to a fixed point) — deterministic (fixed node order, lowest-index tie-break), enough to detect clear communities and drive the meta-node/fracture pipeline. The recursive multi-level aggregation (Louvain proper) and the Leiden refinement (guaranteed well-connected communities) are documented in .nornir/elite-graph-engine.md; they slot in behind louvain without changing the meta-graph / fracture API.

Structs

Communities

A detected partition: of[i] is node i’s community (compact 0..count), with the partition’s modularity as the quality DATA.

MetaGraph

The collapsed graph: one MetaNode per community + aggregated inter-community edges (from_comm, to_comm, weight = crossing-edge count).

MetaNode

One meta-node: a collapsed community — its members, centroid position, and a weight (member count) a renderer can size by.

Functions

fracture_t

The fracture parameter t ∈ [0,1] for the current zoom: 0 = fully collapsed (show meta-nodes), 1 = fully fractured (show members at their real positions). Below collapse_below it’s collapsed; above collapse_below + span it’s open; between, the injected ease drives the bloom (pass facett_core::effects::easing::ease_in_out_cubic / elastic). Deterministic.

fractured_positions

Per-node rendered positions at fracture t: each node lerps from its meta-node centroid (t=0, collapsed) to its real position (t=1, fractured). The host paints nodes with opacity ∝ t (and meta-nodes ∝ 1−t) for the bloom-open.

louvain

Louvain local-moving community detection over an undirected, unweighted graph of n nodes. Greedily moves each node to the neighbouring community with the best modularity gain until a full pass makes no move. Deterministic in (n, edges).

meta_graph

Collapse positions + edges under comms into the meta-graph: meta-node centroids + aggregated crossing edges (intra-community edges vanish into the node).

modularity

Newman modularity Q = (1/2m) Σ_ij [A_ij − k_i k_j/2m] δ(c_i,c_j) of a partition.

visible_count

How many nodes are visible at fracture t: the collapsed meta-node count when t == 0, the full node count when fully fractured — the semantic-zoom LOD DATA.