@optave/codegraph 3.3.0 → 3.4.0

package/src/graph/algorithms/leiden/index.ts

@@ -0,0 +1,185 @@
+/**
+ * Leiden community detection — vendored from ngraph.leiden (MIT).
+ * Adapted to work directly with CodeGraph (no external graph library dependency).
+ *
+ * Original: https://github.com/anvaka/ngraph.leiden
+ * License:  MIT — see LICENSE in this directory.
+ */
+
+import type { CodeGraph } from '../../model.js';
+import type { GraphAdapter } from './adapter.js';
+import { qualityCPM } from './cpm.js';
+import { qualityModularity } from './modularity.js';
+import type { LeidenOptions } from './optimiser.js';
+import { runLouvainUndirectedModularity } from './optimiser.js';
+
+export type { LeidenOptions } from './optimiser.js';
+
+export type DetectClustersOptions = LeidenOptions;
+
+export interface DetectClustersResult {
+  getClass(nodeId: string | number): number | undefined;
+  getCommunities(): Map<number, string[]>;
+  quality(): number;
+  toJSON(): {
+    membership: Record<string, number>;
+    meta: { levels: number; quality: number; options: DetectClustersOptions };
+  };
+}
+
+// Typed array safe-access helpers (see adapter.ts for rationale)
+function fget(a: Float64Array, i: number): number {
+  return a[i] as number;
+}
+function iget(a: Int32Array, i: number): number {
+  return a[i] as number;
+}
+
+/**
+ * Detect communities in a CodeGraph using the Leiden algorithm.
+ *
+ * Note on `quality()`: For modularity, `quality()` always evaluates at gamma=1.0
+ * (standard Newman-Girvan modularity) regardless of the `resolution` used during
+ * optimization. This makes quality values comparable across runs with different
+ * resolutions. For CPM, `quality()` uses the caller-specified resolution since gamma
+ * is intrinsic to the CPM metric. Do not use modularity `quality()` values to
+ * compare partitions found at different resolutions — they reflect Q at gamma=1.0,
+ * not the objective that was actually optimized.
+ */
+export function detectClusters(
+  graph: CodeGraph,
+  options: DetectClustersOptions = {},
+): DetectClustersResult {
+  const { levels, originalToCurrent, originalNodeIds, baseGraph } = runLouvainUndirectedModularity(
+    graph,
+    options,
+  );
+
+  const idToClass = new Map<string, number>();
+  for (let i = 0; i < originalNodeIds.length; i++) {
+    const comm: number = iget(originalToCurrent, i);
+    idToClass.set(originalNodeIds[i]!, comm);
+  }
+
+  return {
+    getClass(nodeId: string | number): number | undefined {
+      return idToClass.get(String(nodeId));
+    },
+    getCommunities(): Map<number, string[]> {
+      const out = new Map<number, string[]>();
+      for (const [id, c] of idToClass) {
+        if (!out.has(c)) out.set(c, []);
+        out.get(c)!.push(id);
+      }
+      return out;
+    },
+    quality(): number {
+      // Compute quality on the original (level-0) graph with the final
+      // partition mapped back. Computing on the last coarse-level graph
+      // produces inflated values because the modularity null model depends
+      // on the degree distribution, which changes after coarsening.
+      const part = buildOriginalPartition(baseGraph, originalToCurrent);
+      const q: string = (options.quality || 'modularity').toLowerCase();
+      if (q === 'cpm') {
+        const gamma: number = typeof options.resolution === 'number' ? options.resolution : 1.0;
+        return qualityCPM(part, baseGraph, gamma);
+      }
+      // Always evaluate at gamma=1.0 for standard Newman-Girvan modularity
+      return qualityModularity(part, baseGraph, 1.0);
+    },
+    toJSON() {
+      const membershipObj: Record<string, number> = {};
+      for (const [id, c] of idToClass) membershipObj[id] = c;
+      return {
+        membership: membershipObj,
+        meta: { levels: levels.length, quality: this.quality(), options },
+      };
+    },
+  };
+}
+
+/**
+ * Minimal partition-like object built from the original graph and the
+ * final community mapping, suitable for qualityModularity / qualityCPM.
+ *
+ * Implements the subset of PartitionView needed by the quality functions
+ * (no scratch-space methods needed since this is read-only evaluation).
+ */
+interface OriginalPartition {
+  communityCount: number;
+  nodeCommunity: Int32Array;
+  communityInternalEdgeWeight: Float64Array;
+  communityTotalStrength: Float64Array;
+  communityTotalOutStrength: Float64Array;
+  communityTotalInStrength: Float64Array;
+  communityTotalSize: Float64Array;
+  // Stub methods required by PartitionView but not called by qualityModularity/qualityCPM
+  getNeighborEdgeWeightToCommunity(c: number): number;
+  getOutEdgeWeightToCommunity(c: number): number;
+  getInEdgeWeightFromCommunity(c: number): number;
+}
+
+function buildOriginalPartition(g: GraphAdapter, communityMap: Int32Array): OriginalPartition {
+  const n: number = g.n;
+  let maxC: number = 0;
+  for (let i = 0; i < n; i++) {
+    const ci = iget(communityMap, i);
+    if (ci > maxC) maxC = ci;
+  }
+  const cc: number = maxC + 1;
+
+  const nodeCommunity = communityMap;
+  const internalWeight = new Float64Array(cc);
+  const totalStr = new Float64Array(cc);
+  const totalOutStr = new Float64Array(cc);
+  const totalInStr = new Float64Array(cc);
+  const totalSize = new Float64Array(cc);
+
+  for (let i = 0; i < n; i++) {
+    const c: number = iget(communityMap, i);
+    totalSize[c] = fget(totalSize, c) + fget(g.size, i);
+    if (g.directed) {
+      totalOutStr[c] = fget(totalOutStr, c) + fget(g.strengthOut, i);
+      totalInStr[c] = fget(totalInStr, c) + fget(g.strengthIn, i);
+    } else {
+      totalStr[c] = fget(totalStr, c) + fget(g.strengthOut, i);
+    }
+    if (fget(g.selfLoop, i)) internalWeight[c] = fget(internalWeight, c) + fget(g.selfLoop, i);
+  }
+
+  if (g.directed) {
+    for (let i = 0; i < n; i++) {
+      const ci: number = iget(communityMap, i);
+      const list = g.outEdges[i]!;
+      for (let k = 0; k < list.length; k++) {
+        const { to: j, w } = list[k]!;
+        if (i === j) continue;
+        if (ci === iget(communityMap, j)) internalWeight[ci] = fget(internalWeight, ci) + w;
+      }
+    }
+  } else {
+    for (let i = 0; i < n; i++) {
+      const ci: number = iget(communityMap, i);
+      const list = g.outEdges[i]!;
+      for (let k = 0; k < list.length; k++) {
+        const { to: j, w } = list[k]!;
+        if (j <= i) continue;
+        if (ci === iget(communityMap, j)) internalWeight[ci] = fget(internalWeight, ci) + w;
+      }
+    }
+  }
+
+  return {
+    communityCount: cc,
+    nodeCommunity,
+    communityInternalEdgeWeight: internalWeight,
+    communityTotalStrength: totalStr,
+    communityTotalOutStrength: totalOutStr,
+    communityTotalInStrength: totalInStr,
+    communityTotalSize: totalSize,
+    // Stubs — quality functions only read the aggregate arrays, not these methods
+    getNeighborEdgeWeightToCommunity: () => 0,
+    getOutEdgeWeightToCommunity: () => 0,
+    getInEdgeWeightFromCommunity: () => 0,
+  };
+}

package/src/graph/algorithms/leiden/modularity.ts

@@ -0,0 +1,122 @@
+/**
+ * Modularity quality functions.
+ * Vendored from ngraph.leiden (MIT) — no external dependencies.
+ */
+
+/**
+ * Minimal view of a partition needed by modularity quality functions.
+ */
+export interface PartitionView {
+  readonly communityCount: number;
+  nodeCommunity: Int32Array;
+  readonly communityInternalEdgeWeight: Float64Array;
+  readonly communityTotalStrength: Float64Array;
+  readonly communityTotalOutStrength: Float64Array;
+  readonly communityTotalInStrength: Float64Array;
+  getNeighborEdgeWeightToCommunity(c: number): number;
+  getOutEdgeWeightToCommunity(c: number): number;
+  getInEdgeWeightFromCommunity(c: number): number;
+}
+
+/**
+ * Minimal view of a graph needed by modularity quality functions.
+ */
+export interface GraphView {
+  n: number;
+  directed: boolean;
+  totalWeight: number;
+  strengthOut: Float64Array;
+  strengthIn: Float64Array;
+  selfLoop: Float64Array;
+}
+
+// Typed array safe-access helper (see adapter.ts for rationale)
+function fget(a: Float64Array, i: number): number {
+  return a[i] as number;
+}
+function iget(a: Int32Array, i: number): number {
+  return a[i] as number;
+}
+
+export function diffModularity(
+  part: PartitionView,
+  g: GraphView,
+  v: number,
+  c: number,
+  gamma: number = 1.0,
+): number {
+  if (g.directed) return diffModularityDirected(part, g, v, c, gamma);
+  const oldC: number = iget(part.nodeCommunity, v);
+  if (c === oldC) return 0;
+  const k_v: number = fget(g.strengthOut, v);
+  const m2: number = g.totalWeight;
+  const k_v_in_new: number = part.getNeighborEdgeWeightToCommunity(c) || 0;
+  const k_v_in_old: number = part.getNeighborEdgeWeightToCommunity(oldC) || 0;
+  const wTot_new: number =
+    c < part.communityTotalStrength.length ? fget(part.communityTotalStrength, c) : 0;
+  const wTot_old: number = fget(part.communityTotalStrength, oldC);
+  const gain_remove: number = -(k_v_in_old / m2 - (gamma * (k_v * wTot_old)) / (m2 * m2));
+  const gain_add: number = k_v_in_new / m2 - (gamma * (k_v * wTot_new)) / (m2 * m2);
+  return gain_remove + gain_add;
+}
+
+export function diffModularityDirected(
+  part: PartitionView,
+  g: GraphView,
+  v: number,
+  c: number,
+  gamma: number = 1.0,
+): number {
+  const oldC: number = iget(part.nodeCommunity, v);
+  if (c === oldC) return 0;
+  const m: number = g.totalWeight;
+  const k_out: number = fget(g.strengthOut, v);
+  const k_in: number = fget(g.strengthIn, v);
+  const w_new_in: number = c < g.n ? part.getInEdgeWeightFromCommunity(c) || 0 : 0;
+  const w_new_out: number = c < g.n ? part.getOutEdgeWeightToCommunity(c) || 0 : 0;
+  const w_old_in: number = part.getInEdgeWeightFromCommunity(oldC) || 0;
+  const w_old_out: number = part.getOutEdgeWeightToCommunity(oldC) || 0;
+  const T_new: number =
+    c < part.communityTotalInStrength.length ? fget(part.communityTotalInStrength, c) : 0;
+  const F_new: number =
+    c < part.communityTotalOutStrength.length ? fget(part.communityTotalOutStrength, c) : 0;
+  const T_old: number = fget(part.communityTotalInStrength, oldC);
+  const F_old: number = fget(part.communityTotalOutStrength, oldC);
+  // Self-loop correction: the self-loop edge (v->v) appears in both
+  // outEdgeWeightToCommunity[oldC] and inEdgeWeightFromCommunity[oldC],
+  // making w_old include 2x selfLoop. Since the self-loop moves with the
+  // node, add it back to match moveNodeToCommunity's directed accounting.
+  const selfW: number = fget(g.selfLoop, v) || 0;
+  const deltaInternal: number = (w_new_in + w_new_out - w_old_in - w_old_out + 2 * selfW) / m;
+  // The full delta(F*T) expansion includes a constant 2*k_out*k_in term that
+  // doesn't depend on the target community but does affect the move-vs-stay
+  // decision. Without it, coarse-level merges can appear profitable when
+  // they actually decrease quality.
+  const deltaExpected: number =
+    (gamma * (k_out * (T_new - T_old) + k_in * (F_new - F_old) + 2 * k_out * k_in)) / (m * m);
+  return deltaInternal - deltaExpected;
+}
+
+export function qualityModularity(part: PartitionView, g: GraphView, gamma: number = 1.0): number {
+  const m2: number = g.totalWeight;
+  let sum: number = 0;
+  if (g.directed) {
+    for (let c = 0; c < part.communityCount; c++)
+      sum +=
+        fget(part.communityInternalEdgeWeight, c) / m2 -
+        (gamma *
+          (fget(part.communityTotalOutStrength, c) * fget(part.communityTotalInStrength, c))) /
+          (m2 * m2);
+  } else {
+    // communityInternalEdgeWeight counts each undirected edge once (j > i),
+    // but m2 = totalWeight = 2m (sum of symmetrized degrees). The standard
+    // Newman-Girvan formula is Q = sum_c [2*L_c/(2m) - gamma*(d_c/(2m))^2], so
+    // we multiply lc by 2 to match.
+    for (let c = 0; c < part.communityCount; c++) {
+      const lc: number = fget(part.communityInternalEdgeWeight, c);
+      const dc: number = fget(part.communityTotalStrength, c);
+      sum += (2 * lc) / m2 - (gamma * (dc * dc)) / (m2 * m2);
+    }
+  }
+  return sum;
+}