@graphty/algorithms 1.8.1 → 2.0.1

package/dist/src/algorithms/community/louvain-optimized.d.ts

@@ -3,13 +3,18 @@ import type { CommunityResult } from "../../types/index.js";
 /**
  * Optimized Louvain community detection algorithm with early pruning and threshold cycling
  *
+ * Runs the full multilevel method of Blondel et al. (local moving, then aggregating each community
+ * into one node, repeated until nothing moves) over typed arrays indexed 0..n-1.
+ *
  * Key optimizations:
- * - Leaf node pruning: Skip nodes with degree 1
+ * - Typed-array adjacency (CSR) instead of per-edge map lookups
+ * - Leaf node pruning: skip a degree-1 node already in its neighbour's community
  * - Importance ordering: Process high-impact nodes first
- * - Threshold cycling: Adaptive convergence thresholds
+ * - Threshold cycling: Adaptive move thresholds, relative to each node's largest possible gain
  * - Early termination: Stop when changes become insignificant
  *
- * Expected speedup: 2-5x on large graphs with many leaf nodes
+ * The graph is treated as undirected: a directed edge counts as an undirected edge of its weight.
+ * A self-loop of weight w adds 2w to its node's degree, the standard convention (NetworkX too).
  */
 interface OptimizedLouvainOptions {
     /**
@@ -17,11 +22,11 @@ interface OptimizedLouvainOptions {
      */
     resolution?: number;
     /**
-     * Maximum iterations per level (default: 100)
+     * Maximum local-moving sweeps per level (default: 100)
      */
     maxIterations?: number;
     /**
-     * Convergence tolerance (default: 1e-6)
+     * Convergence tolerance on a sweep's modularity gain (default: 1e-6)
      */
     tolerance?: number;
     /**
@@ -33,7 +38,7 @@ interface OptimizedLouvainOptions {
      */
     importanceOrdering?: boolean;
     /**
-     * Base pruning threshold (default: 0.01)
+     * Base move threshold, as a fraction of a node's largest possible modularity gain (default: 0.01)
      */
     pruningThreshold?: number;
     /**
@@ -51,11 +56,6 @@ interface PruningStats {
  */
 export declare class OptimizedLouvain {
     private graph;
-    private communities;
-    private communityWeights;
-    private nodeWeights;
-    private nodeDegrees;
-    private totalWeight;
     private pruningStats;
     /**
      * Create an optimized Louvain detector for the given graph
@@ -65,78 +65,34 @@ export declare class OptimizedLouvain {
     /**
      * Run optimized Louvain algorithm
      * @param options - Algorithm configuration options
-     * @returns Community detection result with communities, modularity, and iterations
+     * @returns Community detection result with communities, modularity, and iterations (levels)
      */
     detectCommunities(options?: OptimizedLouvainOptions): CommunityResult;
     /**
-     * Initialize data structures
+     * Get pruning statistics
+     * @returns Statistics about nodes pruned during optimization
      */
-    private initialize;
+    getPruningStats(): PruningStats;
     /**
-     * Get nodes ordered by importance (degree * log(weight))
-     * @returns Array of node IDs sorted by descending importance
+     * Index the graph's nodes 0..n-1 and build the level-0 CSR adjacency
+     * @returns The level-0 graph and the node id at each index
      */
-    private getNodesInImportanceOrder;
+    private buildLevel;
     /**
-     * Perform local moving phase with optimizations
-     * @param nodes - Array of node IDs to process
+     * Move each node to the neighbouring community with the best modularity gain, until no move
+     * improves modularity
+     * @param level - The graph at this level
      * @param options - Local moving options
-     * @param options.pruneLeaves - Whether to skip leaf nodes
-     * @param options.threshold - Minimum gain threshold for moves
-     * @param options.resolution - Resolution parameter for modularity
-     * @returns True if any improvement was made, false otherwise
-     */
-    private performLocalMoving;
-    /**
-     * Check if node is a leaf (degree 1)
-     * @param nodeId - The node ID to check
-     * @returns True if the node has degree 1, false otherwise
+     * @returns Each node's community (numbered 0..count-1), the count, and whether any node moved
      */
-    private isLeafNode;
+    private localMoving;
     /**
-     * Get adaptive threshold that decreases with iterations
-     * @param iteration - Current iteration number
-     * @param baseThreshold - Base threshold value to scale
-     * @returns Adaptive threshold value that decays over iterations
+     * Order nodes for local moving, by importance (degree * log(1 + weighted degree)) if asked
+     * @param level - The graph at this level
+     * @param importanceOrdering - Whether to sort by importance
+     * @returns Node indices in processing order
      */
-    private getAdaptiveThreshold;
-    /**
-     * Calculate modularity gain from moving a node to a community
-     * @param nodeId - The node ID to move
-     * @param targetCommunity - The target community ID
-     * @param resolution - Resolution parameter for modularity calculation
-     * @returns The modularity gain from moving the node
-     */
-    private calculateModularityGain;
-    /**
-     * Remove node from community (for gain calculation)
-     * @param nodeId - The node ID to remove
-     * @param community - The community ID to remove from
-     */
-    private removeNodeFromCommunity;
-    /**
-     * Add node to community
-     * @param nodeId - The node ID to add
-     * @param community - The community ID to add to
-     */
-    private addNodeToCommunity;
-    /**
-     * Get neighboring communities of a node
-     * @param nodeId - The node ID to find neighbor communities for
-     * @returns Set of community IDs that neighbors belong to
-     */
-    private getNeighborCommunities;
-    /**
-     * Calculate total modularity
-     * @param resolution - Resolution parameter for modularity calculation
-     * @returns The modularity score of the current partition
-     */
-    private calculateModularity;
-    /**
-     * Get pruning statistics
-     * @returns Statistics about nodes pruned during optimization
-     */
-    getPruningStats(): PruningStats;
+    private nodeOrder;
 }
 /**
  * Optimized Louvain algorithm with automatic optimization selection

package/dist/src/algorithms/community/louvain-optimized.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"louvain-optimized.d.ts","sourceRoot":"","sources":["../../../../src/algorithms/community/louvain-optimized.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAU,MAAM,sBAAsB,CAAC;AAEpE;;;;;;;;;;GAUG;AAEH,UAAU,uBAAuB;IAC7B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;OAEG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,UAAU,YAAY;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,gBAAgB,CAAsB;IAC9C,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAe;IAEnC;;;OAGG;gBACS,KAAK,EAAE,KAAK;IAcxB;;;;OAIG;IACI,iBAAiB,CAAC,OAAO,GAAE,uBAA4B,GAAG,eAAe;IAmEhF;;OAEG;IACH,OAAO,CAAC,UAAU;IA2ClB;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAiBjC;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAoE1B;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAKlB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAM5B;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAiC/B;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAM/B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAwC3B;;;OAGG;IACI,eAAe,IAAI,YAAY;CAGzC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,uBAA4B,GAAG,eAAe,CAGrG"}
+{"version":3,"file":"louvain-optimized.d.ts","sourceRoot":"","sources":["../../../../src/algorithms/community/louvain-optimized.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAU,MAAM,sBAAsB,CAAC;AAEpE;;;;;;;;;;;;;;;GAeG;AAEH,UAAU,uBAAuB;IAC7B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;OAEG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,UAAU,YAAY;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;CAC7B;AAyBD;;GAEG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,YAAY,CAAe;IAEnC;;;OAGG;gBACS,KAAK,EAAE,KAAK;IASxB;;;;OAIG;IACI,iBAAiB,CAAC,OAAO,GAAE,uBAA4B,GAAG,eAAe;IA8ChF;;;OAGG;IACI,eAAe,IAAI,YAAY;IAItC;;;OAGG;IACH,OAAO,CAAC,UAAU;IAqClB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAiHnB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;CAiBpB;AA+GD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,uBAA4B,GAAG,eAAe,CAGrG"}