@graphty/algorithms 1.6.0 → 1.7.1

package/README.md

@@ -5,6 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@graphty/algorithms.svg)](https://www.npmjs.com/package/@graphty/algorithms)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Documentation](https://img.shields.io/badge/docs-vitepress-blue)](https://graphty.app/docs/algorithms/)
+[![Storybook](https://img.shields.io/badge/storybook-interactive%20demos-ff4785)](https://graphty.app/storybook/algorithms/)
 [![Examples](https://img.shields.io/badge/demo-github%20pages-blue)](https://graphty.app/algorithms/)
 
 A comprehensive TypeScript graph algorithms library with 98 algorithms optimized for browser environments and visualization applications.
@@ -1028,6 +1029,18 @@ const result = grsbm(graph, {
 
 ## Interactive Examples
 
+### Storybook (Recommended)
+
+Explore algorithms with interactive Storybook demos: **[View Storybook →](https://graphty.app/storybook/algorithms/)**
+
+Storybook provides:
+- **Animated visualizations** showing how each algorithm works step-by-step
+- **Interactive controls** to modify parameters and graph types
+- **Deterministic output** with seeded randomness for reproducibility
+- **Visual testing** with Chromatic for regression detection
+
+### Legacy HTML Examples
+
 Try out all algorithms with interactive visualizations: **[Live Demo →](https://graphty.app/algorithms/)**
 
 The library includes comprehensive examples demonstrating each algorithm. You can:

package/dist/algorithms.js

@@ -6370,7 +6370,7 @@ function girvanNewman(graph, options = {}) {
   });
   while (Array.from(workingGraph.edges()).length > 0 && iterations < maxIterations) {
     iterations++;
-    const edgeBetweenness = calculateEdgeBetweenness(workingGraph);
+    const { betweenness: edgeBetweenness, edgeEndpoints } = calculateEdgeBetweenness(workingGraph);
     if (edgeBetweenness.size === 0) {
       break;
     }
@@ -6378,9 +6378,9 @@ function girvanNewman(graph, options = {}) {
     const edgesToRemove = [];
     for (const [edgeKey, centrality] of edgeBetweenness) {
       if (Math.abs(centrality - maxBetweenness) < 1e-10) {
-        const [source, target] = edgeKey.split("|");
-        if (source && target) {
-          edgesToRemove.push({ source, target });
+        const endpoints = edgeEndpoints.get(edgeKey);
+        if (endpoints) {
+          edgesToRemove.push(endpoints);
         }
       }
     }
@@ -6405,9 +6405,11 @@ function girvanNewman(graph, options = {}) {
 }
 function calculateEdgeBetweenness(graph) {
   const edgeBetweenness = /* @__PURE__ */ new Map();
+  const edgeEndpoints = /* @__PURE__ */ new Map();
   for (const edge of graph.edges()) {
     const edgeKey = getEdgeKey(edge.source, edge.target);
     edgeBetweenness.set(edgeKey, 0);
+    edgeEndpoints.set(edgeKey, { source: edge.source, target: edge.target });
   }
   for (const sourceNode of graph.nodes()) {
     const source = sourceNode.id;
@@ -6458,7 +6460,7 @@ function calculateEdgeBetweenness(graph) {
       edgeBetweenness.set(edgeKey, betweenness / 2);
     }
   }
-  return edgeBetweenness;
+  return { betweenness: edgeBetweenness, edgeEndpoints };
 }
 function findAllShortestPaths(graph, source) {
   const distances = /* @__PURE__ */ new Map();
@@ -9022,7 +9024,7 @@ function buildTransitionMatrix(graph, nodeIds, selfLoops) {
   nodeIds.forEach((id, index) => nodeToIndex.set(id, index));
   for (let i = 0; i < n; i++) {
     const nodeId = nodeIds[i];
-    if (!nodeId) {
+    if (nodeId === void 0) {
       continue;
     }
     const neighbors = graph.neighbors(nodeId);
@@ -9221,37 +9223,45 @@ function extractClusters(matrix, nodeIds) {
       attractors.add(nodeId);
     }
   }
-  let clusterIndex = 0;
+  const attractorToCommunity = /* @__PURE__ */ new Map();
   for (let j = 0; j < n; j++) {
-    const clusterNodes = [];
+    let maxVal = 0;
+    let attractorRow = -1;
     for (let i = 0; i < n; i++) {
       const matrixRow = matrix[i];
       if (!matrixRow) {
         continue;
       }
       const val = matrixRow[j];
-      if (val !== void 0 && val > 0 && !nodeToCluster.has(i)) {
-        clusterNodes.push(i);
-        nodeToCluster.set(i, clusterIndex);
+      if (val !== void 0 && val > maxVal) {
+        maxVal = val;
+        attractorRow = i;
       }
     }
-    if (clusterNodes.length > 0) {
-      communities.push(
-        clusterNodes.map((idx) => {
-          const nodeId = nodeIds[idx];
-          return nodeId;
-        }).filter((node) => node !== void 0)
-      );
-      clusterIndex++;
+    if (attractorRow >= 0) {
+      let community = attractorToCommunity.get(attractorRow);
+      if (!community) {
+        community = [];
+        attractorToCommunity.set(attractorRow, community);
+      }
+      community.push(j);
+      nodeToCluster.set(j, attractorRow);
     }
   }
-  for (let i = 0; i < n; i++) {
-    if (!nodeToCluster.has(i)) {
-      const nodeId = nodeIds[i];
+  for (const [, memberIndices] of attractorToCommunity) {
+    communities.push(
+      memberIndices.map((idx) => {
+        const nodeId = nodeIds[idx];
+        return nodeId;
+      }).filter((node) => node !== void 0)
+    );
+  }
+  for (let j = 0; j < n; j++) {
+    if (!nodeToCluster.has(j)) {
+      const nodeId = nodeIds[j];
       if (nodeId !== void 0) {
         communities.push([nodeId]);
       }
-      nodeToCluster.set(i, clusterIndex++);
     }
   }
   return { communities, attractors };
@@ -9281,7 +9291,8 @@ function calculateMCLModularity(graph, communities) {
   return modularity / (2 * m);
 }
 function spectralClustering(graph, options) {
-  const { k, laplacianType = "normalized", maxIterations = 100, tolerance = 1e-4 } = options;
+  const { k, laplacianType = "normalized", maxIterations = 100, tolerance = 1e-4, seed } = options;
+  const random = seed !== void 0 ? SeededRandom.createGenerator(seed) : Math.random;
   if (k < 1 || !Number.isInteger(k)) {
     throw new Error("k must be a positive integer");
   }
@@ -9296,7 +9307,7 @@ function spectralClustering(graph, options) {
   }
   const adjacencyMatrix = buildAdjacencyMatrix(graph, nodeIds);
   const laplacianMatrix = buildLaplacianMatrix(adjacencyMatrix, laplacianType);
-  const eigenResult = findSmallestEigenvectors(laplacianMatrix, k);
+  const eigenResult = findSmallestEigenvectors(laplacianMatrix, k, random);
   const dataPoints = [];
   for (let i = 0; i < nodeIds.length; i++) {
     const point = [];
@@ -9311,7 +9322,7 @@ function spectralClustering(graph, options) {
   if (laplacianType === "normalized") {
     normalizeRows(dataPoints);
   }
-  const kmeans = kMeansClustering(dataPoints, k, maxIterations, tolerance);
+  const kmeans = kMeansClustering(dataPoints, k, maxIterations, tolerance, random);
   const communities = Array.from({ length: k }, () => []);
   const clusterAssignments = /* @__PURE__ */ new Map();
   for (let i = 0; i < nodeIds.length; i++) {
@@ -9462,19 +9473,19 @@ function buildLaplacianMatrix(adjacency, type) {
   }
   return laplacian;
 }
-function findSmallestEigenvectors(matrix, k) {
+function findSmallestEigenvectors(matrix, k, random) {
   const n = matrix.length;
   if (n === 0 || k === 0) {
     return { eigenvalues: [], eigenvectors: [] };
   }
   if (k <= 3 && n > k) {
-    return computeSmallestEigenvectorsSimple(matrix, k, n);
+    return computeSmallestEigenvectorsSimple(matrix, k, n, random);
   }
   const eigenvectors = [];
   const eigenvalues = [];
   const maxIterations = 100;
   for (let eigIdx = 0; eigIdx < k; eigIdx++) {
-    let vector = Array(n).fill(0).map(() => Math.random() - 0.5);
+    let vector = Array(n).fill(0).map(() => random() - 0.5);
     const initNorm = Math.sqrt(vector.reduce((sum, val) => sum + val * val, 0));
     if (initNorm > 0) {
       vector = vector.map((val) => val / initNorm);
@@ -9562,7 +9573,7 @@ function normalizeRows(matrix) {
     }
   }
 }
-function kMeansClustering(data, k, maxIterations, tolerance = 1e-4) {
+function kMeansClustering(data, k, maxIterations, tolerance = 1e-4, random = Math.random) {
   const n = data.length;
   const d = data[0]?.length ?? 0;
   if (n === 0 || k === 0) {
@@ -9577,7 +9588,7 @@ function kMeansClustering(data, k, maxIterations, tolerance = 1e-4) {
   const centroids = [];
   const selectedIndices = /* @__PURE__ */ new Set();
   while (centroids.length < k && selectedIndices.size < n) {
-    const idx = Math.floor(Math.random() * n);
+    const idx = Math.floor(random() * n);
     if (!selectedIndices.has(idx) && data[idx]) {
       selectedIndices.add(idx);
       centroids.push([...data[idx]]);
@@ -9586,7 +9597,7 @@ function kMeansClustering(data, k, maxIterations, tolerance = 1e-4) {
   while (centroids.length < k) {
     const centroid = Array(d).fill(0);
     for (let j = 0; j < d; j++) {
-      centroid[j] = Math.random() - 0.5;
+      centroid[j] = random() - 0.5;
     }
     centroids.push(centroid);
   }
@@ -9682,7 +9693,7 @@ function kMeansClustering(data, k, maxIterations, tolerance = 1e-4) {
   }
   return { assignments, centroids };
 }
-function computeSmallestEigenvectorsSimple(matrix, k, n) {
+function computeSmallestEigenvectorsSimple(matrix, k, n, random) {
   const eigenvectors = [];
   const eigenvalues = [];
   const firstVector = Array(n).fill(1 / Math.sqrt(n));
@@ -9690,7 +9701,7 @@ function computeSmallestEigenvectorsSimple(matrix, k, n) {
   eigenvalues.push(0);
   if (k >= 2) {
     const maxEig = 2;
-    let vector = Array(n).fill(0).map(() => Math.random() - 0.5);
+    let vector = Array(n).fill(0).map(() => random() - 0.5);
     const dot1 = vector.reduce((sum, val) => sum + val / Math.sqrt(n), 0);
     vector = vector.map((val) => val - dot1 / Math.sqrt(n));
     for (let iter = 0; iter < 100; iter++) {
@@ -9718,7 +9729,7 @@ function computeSmallestEigenvectorsSimple(matrix, k, n) {
     eigenvalues.push(0.1);
   }
   if (k >= 3) {
-    let vector = Array(n).fill(0).map(() => Math.random() - 0.5);
+    let vector = Array(n).fill(0).map(() => random() - 0.5);
     for (const prev of eigenvectors) {
       const dot = vector.reduce((sum, val, idx) => sum + val * (prev[idx] ?? 0), 0);
       vector = vector.map((val, idx) => val - dot * (prev[idx] ?? 0));