@graphty/algorithms 1.2.0 → 1.4.2

package/src/algorithms/community/label-propagation.ts

@@ -9,6 +9,10 @@
  * detect community structures in large-scale networks"
  */
 
+import type { Graph } from "../../core/graph.js";
+import { graphToMap } from "../../utils/graph-converters.js";
+import { SeededRandom, shuffle } from "../../utils/math-utilities.js";
+
 export interface LabelPropagationOptions {
     maxIterations?: number;
     randomSeed?: number;
@@ -21,24 +25,16 @@ export interface LabelPropagationResult {
 }
 
 /**
- * Label Propagation Algorithm
- * Each node adopts the most frequent label among its neighbors
- *
- * @param graph - Undirected graph (can be weighted)
- * @param options - Algorithm options
- * @returns Community assignments
- *
- * Time Complexity: O(m) per iteration, typically O(km) for k iterations
- * Space Complexity: O(n)
+ * Internal implementation of Label Propagation Algorithm
+ * @param graph - Map representation of the graph (node to neighbors with weights)
+ * @param options - Algorithm configuration options
+ * @returns Community assignments, iteration count, and convergence status
  */
-export function labelPropagation(
+function labelPropagationImpl(
     graph: Map<string, Map<string, number>>,
     options: LabelPropagationOptions = {},
 ): LabelPropagationResult {
-    const {
-        maxIterations = 100,
-        randomSeed = 42,
-    } = options;
+    const { maxIterations = 100, randomSeed = 42 } = options;
 
     if (graph.size === 0) {
         return {
@@ -49,11 +45,7 @@ export function labelPropagation(
     }
 
     // Initialize random number generator
-    let seed = randomSeed;
-    const random = (): number => {
-        seed = ((seed * 1664525) + 1013904223) % 2147483647;
-        return seed / 2147483647;
-    };
+    const random = SeededRandom.createGenerator(randomSeed);
 
     // Initialize labels - each node gets its own label
     const labels = new Map<string, number>();
@@ -69,7 +61,7 @@ export function labelPropagation(
         converged = true;
 
         // Create random order for node updates
-        const nodeOrder = [... nodes];
+        const nodeOrder = [...nodes];
         shuffle(nodeOrder, random);
 
         // Update each node's label
@@ -157,16 +149,17 @@ export function labelPropagation(
 }
 
 /**
- * Asynchronous Label Propagation
+ * Internal implementation of Asynchronous Label Propagation
  * Updates all nodes simultaneously (can lead to oscillations)
+ * @param graph - Map representation of the graph (node to neighbors with weights)
+ * @param options - Algorithm configuration options
+ * @returns Community assignments, iteration count, and convergence status
  */
-export function labelPropagationAsync(
+function labelPropagationAsyncImpl(
     graph: Map<string, Map<string, number>>,
     options: LabelPropagationOptions = {},
 ): LabelPropagationResult {
-    const {
-        maxIterations = 100,
-    } = options;
+    const { maxIterations = 100 } = options;
 
     if (graph.size === 0) {
         return {
@@ -267,30 +260,27 @@ export function labelPropagationAsync(
 }
 
 /**
- * Semi-supervised Label Propagation
+ * Internal implementation of Semi-supervised Label Propagation
  * Some nodes have fixed labels that don't change
+ * @param graph - Map representation of the graph (node to neighbors with weights)
+ * @param seedLabels - Map of node IDs to their fixed community labels
+ * @param options - Algorithm configuration options
+ * @returns Community assignments, iteration count, and convergence status
  */
-export function labelPropagationSemiSupervised(
+function labelPropagationSemiSupervisedImpl(
     graph: Map<string, Map<string, number>>,
     seedLabels: Map<string, number>,
     options: LabelPropagationOptions = {},
 ): LabelPropagationResult {
-    const {
-        maxIterations = 100,
-        randomSeed = 42,
-    } = options;
+    const { maxIterations = 100, randomSeed = 42 } = options;
 
     // Initialize random number generator
-    let seed = randomSeed;
-    const random = (): number => {
-        seed = ((seed * 1664525) + 1013904223) % 2147483647;
-        return seed / 2147483647;
-    };
+    const random = SeededRandom.createGenerator(randomSeed);
 
     // Initialize labels
     const labels = new Map<string, number>();
     const nodes = Array.from(graph.keys());
-    let labelCounter = Math.max(... Array.from(seedLabels.values())) + 1;
+    let labelCounter = Math.max(...Array.from(seedLabels.values())) + 1;
 
     for (const node of nodes) {
         if (seedLabels.has(node)) {
@@ -376,17 +366,48 @@ export function labelPropagationSemiSupervised(
 }
 
 /**
- * Fisher-Yates shuffle
+ * Label Propagation Algorithm
+ * Each node adopts the most frequent label among its neighbors
+ * @param graph - Undirected graph (can be weighted)
+ * @param options - Algorithm options
+ * @returns Community assignments
+ *
+ * Time Complexity: O(m) per iteration, typically O(km) for k iterations
+ * Space Complexity: O(n)
+ */
+export function labelPropagation(graph: Graph, options: LabelPropagationOptions = {}): LabelPropagationResult {
+    // Convert Graph to Map representation
+    const graphMap = graphToMap(graph);
+    return labelPropagationImpl(graphMap, options);
+}
+
+/**
+ * Asynchronous Label Propagation
+ * Updates all nodes simultaneously (can lead to oscillations)
+ * @param graph - Undirected graph (can be weighted)
+ * @param options - Algorithm options
+ * @returns Community assignments
  */
-function shuffle(array: unknown[], random: () => number): void {
-    for (let i = array.length - 1; i > 0; i--) {
-        const j = Math.floor(random() * (i + 1));
-        const temp = array[i];
-        const swapItem = array[j];
-        if (temp !== undefined && swapItem !== undefined) {
-            array[i] = swapItem;
-            array[j] = temp;
-        }
-    }
+export function labelPropagationAsync(graph: Graph, options: LabelPropagationOptions = {}): LabelPropagationResult {
+    // Convert Graph to Map representation
+    const graphMap = graphToMap(graph);
+    return labelPropagationAsyncImpl(graphMap, options);
 }
 
+/**
+ * Semi-supervised Label Propagation
+ * Some nodes have fixed labels that don't change
+ * @param graph - Undirected graph (can be weighted)
+ * @param seedLabels - Initial fixed labels for some nodes
+ * @param options - Algorithm options
+ * @returns Community assignments
+ */
+export function labelPropagationSemiSupervised(
+    graph: Graph,
+    seedLabels: Map<string, number>,
+    options: LabelPropagationOptions = {},
+): LabelPropagationResult {
+    // Convert Graph to Map representation
+    const graphMap = graphToMap(graph);
+    return labelPropagationSemiSupervisedImpl(graphMap, seedLabels, options);
+}

package/src/algorithms/community/leiden.ts

@@ -8,7 +8,9 @@
  * "From Louvain to Leiden: guaranteeing well-connected communities"
  */
 
-// Louvain import removed - not used in this implementation
+import type { Graph } from "../../core/graph.js";
+import { graphToMap } from "../../utils/graph-converters.js";
+import { SeededRandom, shuffle } from "../../utils/math-utilities.js";
 
 export interface LeidenOptions {
     resolution?: number;
@@ -24,29 +26,17 @@ export interface LeidenResult {
 }
 
 /**
- * Leiden algorithm for community detection
+ * Internal implementation of Leiden algorithm for community detection
  * Improves upon Louvain by ensuring well-connected communities
- *
- * @param graph - Undirected weighted graph
- * @param options - Algorithm options
- * @returns Community assignments and modularity
- *
- * Time Complexity: O(m) per iteration, typically O(m log m) total
- * Space Complexity: O(n + m)
+ * @param inputGraph - Map representation of the graph (node to neighbors with weights)
+ * @param options - Algorithm configuration options
+ * @returns Community assignments, modularity score, and iteration count
  */
-export function leiden(
-    graph: Map<string, Map<string, number>>,
-    options: LeidenOptions = {},
-): LeidenResult {
-    const {
-        resolution = 1.0,
-        randomSeed = 42,
-        maxIterations = 100,
-        threshold = 1e-7,
-    } = options;
+function leidenImpl(inputGraph: Map<string, Map<string, number>>, options: LeidenOptions = {}): LeidenResult {
+    const { resolution = 1.0, randomSeed = 42, maxIterations = 100, threshold = 1e-7 } = options;
 
     // Handle empty graph
-    if (graph.size === 0) {
+    if (inputGraph.size === 0) {
         return {
             communities: new Map(),
             modularity: 0,
@@ -54,18 +44,17 @@ export function leiden(
         };
     }
 
+    // Use a mutable variable for the current graph state
+    let currentGraph = inputGraph;
+
     // Initialize random number generator
-    let seed = randomSeed;
-    const random = (): number => {
-        seed = ((seed * 1664525) + 1013904223) % 2147483647;
-        return seed / 2147483647;
-    };
+    const random = SeededRandom.createGenerator(randomSeed);
 
     // Calculate total weight
     let totalWeight = 0;
     const degrees = new Map<string, number>();
 
-    for (const [node, neighbors] of graph) {
+    for (const [node, neighbors] of currentGraph) {
         let degree = 0;
         for (const weight of neighbors.values()) {
             degree += weight;
@@ -77,10 +66,10 @@ export function leiden(
 
     // Initialize communities - each node in its own community
     const communities = new Map<string, number>();
-    const nodes = Array.from(graph.keys());
+    const nodes = Array.from(currentGraph.keys());
     nodes.forEach((node, i) => communities.set(node, i));
 
-    let modularity = calculateModularity(graph, communities, degrees, totalWeight, resolution);
+    let modularity = calculateModularity(currentGraph, communities, degrees, totalWeight, resolution);
     let bestModularity = modularity;
     let bestCommunities = new Map(communities);
     let iterations = 0;
@@ -91,7 +80,7 @@ export function leiden(
         let improved = false;
 
         // Phase 1: Local moving of nodes (fast)
-        const nodeOrder = [... nodes];
+        const nodeOrder = [...nodes];
         shuffle(nodeOrder, random);
 
         for (const node of nodeOrder) {
@@ -100,7 +89,7 @@ export function leiden(
                 continue;
             }
 
-            const neighborCommunities = getNeighborCommunities(node, graph, communities);
+            const neighborCommunities = getNeighborCommunities(node, currentGraph, communities);
 
             let bestCommunity = currentCommunity;
             let bestGain = 0;
@@ -112,7 +101,13 @@ export function leiden(
                 }
 
                 const gain = calculateModularityGain(
-                    node, community, graph, communities, degrees, totalWeight, resolution,
+                    node,
+                    community,
+                    currentGraph,
+                    communities,
+                    degrees,
+                    totalWeight,
+                    resolution,
                 );
 
                 if (gain > bestGain) {
@@ -131,12 +126,10 @@ export function leiden(
 
         // Phase 2: Refinement (Leiden improvement over Louvain)
         // Create aggregate network based on current partition
-        createAggregateNetwork(graph, communities);
+        createAggregateNetwork(currentGraph, communities);
 
         // Refine partition using aggregate network
-        const subsetPartition = refinePartition(
-            graph, communities,
-        );
+        const subsetPartition = refinePartition(currentGraph, communities);
 
         // Apply refined partition
         for (const [node, newCommunity] of subsetPartition) {
@@ -144,7 +137,7 @@ export function leiden(
         }
 
         // Recalculate modularity
-        modularity = calculateModularity(graph, communities, degrees, totalWeight, resolution);
+        modularity = calculateModularity(currentGraph, communities, degrees, totalWeight, resolution);
 
         // Check if we've improved
         if (modularity > bestModularity + threshold) {
@@ -158,17 +151,17 @@ export function leiden(
         }
 
         // Phase 3: Aggregate network (create super-nodes)
-        const aggregated = aggregateCommunities(graph, communities);
-        if (aggregated.graph.size === graph.size) {
+        const aggregated = aggregateCommunities(currentGraph, communities);
+        if (aggregated.graph.size === currentGraph.size) {
             break;
         } // No aggregation possible
 
         // Continue with aggregated network
-        const {graph: newGraph} = aggregated;
-        graph = newGraph;
+        const { graph: aggregatedGraph } = aggregated;
+        currentGraph = aggregatedGraph;
         communities.clear();
         let communityId = 0;
-        for (const node of graph.keys()) {
+        for (const node of currentGraph.keys()) {
             communities.set(node, communityId++);
         }
     }
@@ -201,6 +194,12 @@ export function leiden(
 
 /**
  * Calculate modularity of a partition
+ * @param graph - Map representation of the graph
+ * @param communities - Map of node IDs to community IDs
+ * @param degrees - Map of node IDs to their weighted degrees
+ * @param totalWeight - Total weight of all edges in the graph
+ * @param resolution - Resolution parameter for modularity calculation
+ * @returns The modularity score of the partition
  */
 function calculateModularity(
     graph: Map<string, Map<string, number>>,
@@ -242,11 +241,11 @@ function calculateModularity(
     }
 
     // Normalize and apply resolution
-    modularity /= (2 * totalWeight);
+    modularity /= 2 * totalWeight;
 
     // Subtract expected edges
     for (const weight of communityWeights.values()) {
-        modularity -= resolution * ((weight / (2 * totalWeight)) ** 2);
+        modularity -= resolution * (weight / (2 * totalWeight)) ** 2;
     }
 
     return modularity;
@@ -254,6 +253,10 @@ function calculateModularity(
 
 /**
  * Get communities of neighbors
+ * @param node - The node ID to get neighbor communities for
+ * @param graph - Map representation of the graph
+ * @param communities - Map of node IDs to community IDs
+ * @returns Map of community IDs to total edge weight connecting to that community
  */
 function getNeighborCommunities(
     node: string,
@@ -277,6 +280,14 @@ function getNeighborCommunities(
 
 /**
  * Calculate modularity gain from moving a node to a community
+ * @param node - The node ID to move
+ * @param targetCommunity - The target community ID
+ * @param graph - Map representation of the graph
+ * @param communities - Map of node IDs to community IDs
+ * @param degrees - Map of node IDs to their weighted degrees
+ * @param totalWeight - Total weight of all edges in the graph
+ * @param resolution - Resolution parameter for modularity calculation
+ * @returns The modularity gain from moving the node to the target community
  */
 function calculateModularityGain(
     node: string,
@@ -333,22 +344,26 @@ function calculateModularityGain(
 
     // Modularity gain calculation
     const m2 = 2 * totalWeight;
-    const gain = ((weightToTarget - weightToCurrent) / totalWeight) -
-    (resolution * nodeDegree * (targetDegree - currentDegree) / (m2 * m2));
+    const gain =
+        (weightToTarget - weightToCurrent) / totalWeight -
+        (resolution * nodeDegree * (targetDegree - currentDegree)) / (m2 * m2);
 
     return gain;
 }
 
 /**
  * Create aggregate network where each community becomes a super-node
+ * @param graph - Map representation of the graph
+ * @param communities - Map of node IDs to community IDs
+ * @returns Object with aggregate graph and node-to-community mapping
  */
 function createAggregateNetwork(
     graph: Map<string, Map<string, number>>,
     communities: Map<string, number>,
 ): {
-        aggregateGraph: Map<number, Map<number, number>>;
-        nodeMapping: Map<string, number>;
-    } {
+    aggregateGraph: Map<number, Map<number, number>>;
+    nodeMapping: Map<string, number>;
+} {
     const aggregateGraph = new Map<number, Map<number, number>>();
     const nodeMapping = new Map<string, number>();
 
@@ -381,12 +396,15 @@ function createAggregateNetwork(
         }
     }
 
-    return {aggregateGraph, nodeMapping};
+    return { aggregateGraph, nodeMapping };
 }
 
 /**
  * Refine partition (Leiden-specific improvement)
  * Ensures well-connected communities by considering subsets
+ * @param originalGraph - Map representation of the original graph
+ * @param communities - Map of node IDs to community IDs
+ * @returns Refined community assignments with well-connected communities
  */
 function refinePartition(
     originalGraph: Map<string, Map<string, number>>,
@@ -454,6 +472,8 @@ function refinePartition(
 
 /**
  * Find connected components in undirected graph
+ * @param graph - Map representation of the graph (node to set of neighbors)
+ * @returns Array of connected components (each is a set of node IDs)
  */
 function findConnectedComponents(graph: Map<string, Set<string>>): Set<string>[] {
     const visited = new Set<string>();
@@ -492,14 +512,17 @@ function findConnectedComponents(graph: Map<string, Set<string>>): Set<string>[]
 
 /**
  * Aggregate communities into super-nodes
+ * @param graph - Map representation of the graph
+ * @param communities - Map of node IDs to community IDs
+ * @returns Object with aggregated graph and node-to-supernode mapping
  */
 function aggregateCommunities(
     graph: Map<string, Map<string, number>>,
     communities: Map<string, number>,
 ): {
-        graph: Map<string, Map<string, number>>;
-        mapping: Map<string, string>;
-    } {
+    graph: Map<string, Map<string, number>>;
+    mapping: Map<string, string>;
+} {
     const aggregated = new Map<string, Map<string, number>>();
     const mapping = new Map<string, string>();
 
@@ -552,21 +575,21 @@ function aggregateCommunities(
         }
     }
 
-    return {graph: aggregated, mapping};
+    return { graph: aggregated, mapping };
 }
 
 /**
- * Fisher-Yates shuffle
+ * Leiden algorithm for community detection
+ * Improves upon Louvain by ensuring well-connected communities
+ * @param graph - Undirected weighted graph - accepts Graph class or Map representation
+ * @param options - Algorithm options
+ * @returns Community assignments and modularity
+ *
+ * Time Complexity: O(m) per iteration, typically O(m log m) total
+ * Space Complexity: O(n + m)
  */
-function shuffle(array: unknown[], random: () => number): void {
-    for (let i = array.length - 1; i > 0; i--) {
-        const j = Math.floor(random() * (i + 1));
-        const temp = array[i];
-        const swapItem = array[j];
-        if (temp !== undefined && swapItem !== undefined) {
-            array[i] = swapItem;
-            array[j] = temp;
-        }
-    }
+export function leiden(graph: Graph, options: LeidenOptions = {}): LeidenResult {
+    // Convert Graph to Map representation
+    const graphMap = graphToMap(graph);
+    return leidenImpl(graphMap, options);
 }
-