@graphty/layout 1.1.1 → 1.2.1

package/src/layouts/force-directed/forceatlas2.ts

@@ -0,0 +1,407 @@
+import type { Graph, Node, Edge, PositionMap } from '../../types';
+import { getNodesFromGraph, getEdgesFromGraph } from '../../utils/graph';
+import { _processParams } from '../../utils/params';
+import { rescaleLayout } from '../../utils/rescale';
+import { RandomNumberGenerator } from '../../utils/random';
+
+/**
+ * Position nodes using the ForceAtlas2 force-directed algorithm.
+ * 
+ * @param G - Graph
+ * @param pos - Initial positions for nodes
+ * @param maxIter - Maximum number of iterations
+ * @param jitterTolerance - Controls tolerance for node speed adjustments
+ * @param scalingRatio - Scaling of attraction and repulsion forces
+ * @param gravity - Attraction to center to prevent disconnected components from drifting
+ * @param distributedAction - Distributes attraction force among nodes
+ * @param strongGravity - Uses a stronger gravity model
+ * @param nodeMass - Dictionary mapping nodes to their masses
+ * @param nodeSize - Dictionary mapping nodes to their sizes
+ * @param weight - Edge attribute for weight
+ * @param dissuadeHubs - Whether to prevent hub nodes from clustering
+ * @param linlog - Whether to use logarithmic attraction
+ * @param seed - Random seed for initial positions
+ * @param dim - Dimension of layout
+ * @returns Positions dictionary keyed by node
+ */
+export function forceatlas2Layout(
+  G: Graph,
+  pos: PositionMap | null = null,
+  maxIter: number = 100,
+  jitterTolerance: number = 1.0,
+  scalingRatio: number = 2.0,
+  gravity: number = 1.0,
+  distributedAction: boolean = false,
+  strongGravity: boolean = false,
+  nodeMass: Record<Node, number> | null = null,
+  nodeSize: Record<Node, number> | null = null,
+  weight: string | null = null,
+  dissuadeHubs: boolean = false,
+  linlog: boolean = false,
+  seed: number | null = null,
+  dim: number = 2
+): PositionMap {
+  const processed = _processParams(G, null, dim);
+  const graph = processed.G;
+
+  const nodes = getNodesFromGraph(graph);
+
+  if (nodes.length === 0) {
+    return {};
+  }
+
+  // Initialize random number generator
+  const rng = new RandomNumberGenerator(seed ?? undefined);
+
+  // Initialize positions if not provided
+  let posArray: number[][];
+  if (pos === null) {
+    pos = {};
+    posArray = new Array(nodes.length);
+    for (let i = 0; i < nodes.length; i++) {
+      posArray[i] = Array(dim).fill(0).map(() => rng.rand() as number * 2 - 1);
+      pos[nodes[i]] = posArray[i];
+    }
+  } else if (Object.keys(pos).length === nodes.length) {
+    // Use provided positions
+    posArray = new Array(nodes.length);
+    for (let i = 0; i < nodes.length; i++) {
+      posArray[i] = [...pos[nodes[i]]];
+    }
+  } else {
+    // Some nodes don't have positions, initialize within the range of existing positions
+    let minPos = Array(dim).fill(Number.POSITIVE_INFINITY);
+    let maxPos = Array(dim).fill(Number.NEGATIVE_INFINITY);
+
+    // Find min and max of existing positions
+    for (const node in pos) {
+      for (let d = 0; d < dim; d++) {
+        minPos[d] = Math.min(minPos[d], pos[node][d]);
+        maxPos[d] = Math.max(maxPos[d], pos[node][d]);
+      }
+    }
+
+    posArray = new Array(nodes.length);
+    for (let i = 0; i < nodes.length; i++) {
+      const node = nodes[i];
+      if (pos[node]) {
+        posArray[i] = [...pos[node]];
+      } else {
+        posArray[i] = Array(dim).fill(0).map((_, d) =>
+          minPos[d] + (rng.rand() as number) * (maxPos[d] - minPos[d])
+        );
+        pos[node] = posArray[i];
+      }
+    }
+  }
+
+  // Initialize mass and size arrays
+  const mass = new Array(nodes.length).fill(0);
+  const size = new Array(nodes.length).fill(0);
+
+  // Flag to track whether to adjust for node sizes
+  const adjustSizes = nodeSize !== null;
+
+  // Set node masses and sizes
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i];
+    mass[i] = nodeMass && nodeMass[node] ?
+      nodeMass[node] :
+      (Array.isArray(graph) ? 1 : getNodeDegree(graph, node) + 1);
+
+    size[i] = nodeSize && nodeSize[node] ? nodeSize[node] : 1;
+  }
+
+  // Create adjacency matrix
+  const n = nodes.length;
+  const A = Array(n).fill(0).map(() => Array(n).fill(0));
+
+  // Populate adjacency matrix with edge weights
+  const edges = Array.isArray(graph) ? [] as Edge[] : graph.edges();
+  const nodeIndices: Record<Node, number> = {};
+  nodes.forEach((node, i) => { nodeIndices[node] = i; });
+
+  for (const [source, target] of edges) {
+    const i = nodeIndices[source];
+    const j = nodeIndices[target];
+
+    // Use edge weight if provided, otherwise default to 1
+    let edgeWeight = 1;
+    if (weight && !Array.isArray(graph) && graph.getEdgeData) {
+      edgeWeight = graph.getEdgeData(source, target, weight) || 1;
+    }
+
+    A[i][j] = edgeWeight;
+    A[j][i] = edgeWeight; // For undirected graphs
+  }
+
+  // Initialize force arrays
+  const gravities = Array(n).fill(0).map(() => Array(dim).fill(0));
+  const attraction = Array(n).fill(0).map(() => Array(dim).fill(0));
+  const repulsion = Array(n).fill(0).map(() => Array(dim).fill(0));
+
+  // Simulation parameters
+  let speed = 1;
+  let speedEfficiency = 1;
+  let swing = 1;
+  let traction = 1;
+
+  // Helper function to estimate factor for force scaling
+  function estimateFactor(
+    n: number,
+    swing: number,
+    traction: number,
+    speed: number,
+    speedEfficiency: number,
+    jitterTolerance: number
+  ): [number, number] {
+    // Optimal jitter parameters
+    const optJitter = 0.05 * Math.sqrt(n);
+    const minJitter = Math.sqrt(optJitter);
+    const maxJitter = 10;
+    const minSpeedEfficiency = 0.05;
+
+    // Estimate jitter based on current state
+    const other = Math.min(maxJitter, optJitter * traction / (n * n));
+    let jitter = jitterTolerance * Math.max(minJitter, other);
+
+    // Adjust speed efficiency based on swing/traction ratio
+    if (swing / traction > 2.0) {
+      if (speedEfficiency > minSpeedEfficiency) {
+        speedEfficiency *= 0.5;
+      }
+      jitter = Math.max(jitter, jitterTolerance);
+    }
+
+    // Calculate target speed
+    let targetSpeed = swing === 0 ?
+      Number.POSITIVE_INFINITY :
+      jitter * speedEfficiency * traction / swing;
+
+    // Further adjust speed efficiency
+    if (swing > jitter * traction) {
+      if (speedEfficiency > minSpeedEfficiency) {
+        speedEfficiency *= 0.7;
+      }
+    } else if (speed < 1000) {
+      speedEfficiency *= 1.3;
+    }
+
+    // Limit the speed increase
+    const maxRise = 0.5;
+    speed = speed + Math.min(targetSpeed - speed, maxRise * speed);
+
+    return [speed, speedEfficiency];
+  }
+
+  // Main simulation loop
+  for (let iter = 0; iter < maxIter; iter++) {
+    // Reset forces for this iteration
+    for (let i = 0; i < n; i++) {
+      for (let d = 0; d < dim; d++) {
+        attraction[i][d] = 0;
+        repulsion[i][d] = 0;
+        gravities[i][d] = 0;
+      }
+    }
+
+    // Compute pairwise differences and distances
+    const diff = Array(n).fill(0).map(() =>
+      Array(n).fill(0).map(() => Array(dim).fill(0))
+    );
+
+    const distance = Array(n).fill(0).map(() => Array(n).fill(0));
+
+    for (let i = 0; i < n; i++) {
+      for (let j = 0; j < n; j++) {
+        if (i === j) continue;
+
+        for (let d = 0; d < dim; d++) {
+          diff[i][j][d] = posArray[i][d] - posArray[j][d];
+        }
+
+        distance[i][j] = Math.sqrt(diff[i][j].reduce((sum, d) => sum + d * d, 0));
+        // Prevent division by zero
+        if (distance[i][j] < 0.01) distance[i][j] = 0.01;
+      }
+    }
+
+    // Calculate attraction forces
+    if (linlog) {
+      // Logarithmic attraction model
+      for (let i = 0; i < n; i++) {
+        for (let j = 0; j < n; j++) {
+          if (i === j || A[i][j] === 0) continue;
+
+          const dist = distance[i][j];
+          const factor = -Math.log(1 + dist) / dist * A[i][j];
+
+          for (let d = 0; d < dim; d++) {
+            const force = factor * diff[i][j][d];
+            attraction[i][d] += force;
+          }
+        }
+      }
+    } else {
+      // Linear attraction model
+      for (let i = 0; i < n; i++) {
+        for (let j = 0; j < n; j++) {
+          if (i === j || A[i][j] === 0) continue;
+
+          for (let d = 0; d < dim; d++) {
+            const force = -diff[i][j][d] * A[i][j];
+            attraction[i][d] += force;
+          }
+        }
+      }
+    }
+
+    // Apply distributed attraction if enabled
+    if (distributedAction) {
+      for (let i = 0; i < n; i++) {
+        for (let d = 0; d < dim; d++) {
+          attraction[i][d] /= mass[i];
+        }
+      }
+    }
+
+    // Calculate repulsion forces
+    for (let i = 0; i < n; i++) {
+      for (let j = 0; j < n; j++) {
+        if (i === j) continue;
+
+        let dist = distance[i][j];
+
+        // Adjust distance for node sizes if needed
+        if (adjustSizes) {
+          dist -= size[i] - size[j];
+          dist = Math.max(dist, 0.01); // Prevent negative or zero distances
+        }
+
+        const distSquared = dist * dist;
+        const massProduct = mass[i] * mass[j];
+        const factor = (massProduct / distSquared) * scalingRatio;
+
+        for (let d = 0; d < dim; d++) {
+          const direction = diff[i][j][d] / dist;
+          repulsion[i][d] += direction * factor;
+        }
+      }
+    }
+
+    // Calculate gravity forces
+    // First find the center of mass
+    const centerOfMass = Array(dim).fill(0);
+    for (let i = 0; i < n; i++) {
+      for (let d = 0; d < dim; d++) {
+        centerOfMass[d] += posArray[i][d] / n;
+      }
+    }
+
+    for (let i = 0; i < n; i++) {
+      const posCentered = Array(dim);
+      for (let d = 0; d < dim; d++) {
+        posCentered[d] = posArray[i][d] - centerOfMass[d];
+      }
+
+      if (strongGravity) {
+        // Strong gravity model
+        for (let d = 0; d < dim; d++) {
+          gravities[i][d] = -gravity * mass[i] * posCentered[d];
+        }
+      } else {
+        // Regular gravity model
+        const dist = Math.sqrt(posCentered.reduce((sum, val) => sum + val * val, 0));
+
+        if (dist > 0.01) {
+          for (let d = 0; d < dim; d++) {
+            const direction = posCentered[d] / dist;
+            gravities[i][d] = -gravity * mass[i] * direction;
+          }
+        }
+      }
+    }
+
+    // Calculate total forces and update positions
+    const update = Array(n).fill(0).map(() => Array(dim).fill(0));
+    let totalSwing = 0;
+    let totalTraction = 0;
+
+    for (let i = 0; i < n; i++) {
+      for (let d = 0; d < dim; d++) {
+        update[i][d] = attraction[i][d] + repulsion[i][d] + gravities[i][d];
+      }
+
+      // Calculate swing and traction for this node
+      const oldPos = [...posArray[i]];
+      const newPos = oldPos.map((p, d) => p + update[i][d]);
+
+      const swingVector = oldPos.map((p, d) => p - newPos[d]);
+      const tractionVector = oldPos.map((p, d) => p + newPos[d]);
+
+      const swingMagnitude = Math.sqrt(swingVector.reduce((sum, val) => sum + val * val, 0));
+      const tractionMagnitude = Math.sqrt(tractionVector.reduce((sum, val) => sum + val * val, 0));
+
+      totalSwing += mass[i] * swingMagnitude;
+      totalTraction += 0.5 * mass[i] * tractionMagnitude;
+    }
+
+    // Update speed and efficiency
+    [speed, speedEfficiency] = estimateFactor(
+      n,
+      totalSwing,
+      totalTraction,
+      speed,
+      speedEfficiency,
+      jitterTolerance
+    );
+
+    // Apply forces to update positions
+    let totalMovement = 0;
+
+    for (let i = 0; i < n; i++) {
+      let factor;
+
+      if (adjustSizes) {
+        // Calculate displacement magnitude
+        const df = Math.sqrt(update[i].reduce((sum, val) => sum + val * val, 0));
+        const swinging = mass[i] * df;
+
+        // Determine scaling factor with size adjustments
+        factor = 0.1 * speed / (1 + Math.sqrt(speed * swinging));
+        factor = Math.min(factor * df, 10) / df;
+      } else {
+        // Standard scaling factor
+        const swinging = mass[i] * Math.sqrt(update[i].reduce((sum, val) => sum + val * val, 0));
+        factor = speed / (1 + Math.sqrt(speed * swinging));
+      }
+
+      // Apply factor to update position
+      for (let d = 0; d < dim; d++) {
+        const movement = update[i][d] * factor;
+        posArray[i][d] += movement;
+        totalMovement += Math.abs(movement);
+      }
+    }
+
+    // Check for convergence
+    if (totalMovement < 1e-10) {
+      break;
+    }
+  }
+
+  // Create position dictionary
+  const positions: PositionMap = {};
+  for (let i = 0; i < n; i++) {
+    positions[nodes[i]] = posArray[i];
+  }
+
+  return rescaleLayout(positions) as PositionMap;
+}
+
+// Helper function to get node degree
+function getNodeDegree(graph: Graph, node: Node): number {
+  return graph.edges().filter((edge: Edge) =>
+    edge[0] === node || edge[1] === node
+  ).length;
+}

package/src/layouts/force-directed/fruchterman-reingold.ts

@@ -0,0 +1,164 @@
+/**
+ * Fruchterman-Reingold force-directed layout algorithm
+ */
+
+import { Graph, Node, Edge, PositionMap } from '../../types';
+import { _processParams } from '../../utils/params';
+import { getNodesFromGraph, getEdgesFromGraph } from '../../utils/graph';
+import { RandomNumberGenerator } from '../../utils/random';
+import { rescaleLayout } from '../../utils/rescale';
+
+/**
+ * Position nodes using Fruchterman-Reingold force-directed algorithm.
+ *
+ * @param {Object} G - Graph or list of nodes
+ * @param {number} k - Optimal distance between nodes
+ * @param {Object} pos - Initial positions for nodes
+ * @param {Array} fixed - Nodes to keep fixed at initial position
+ * @param {number} iterations - Maximum number of iterations
+ * @param {number} scale - Scale factor for positions
+ * @param {Array|null} center - Coordinate pair around which to center the layout
+ * @param {number} dim - Dimension of layout
+ * @param {number} seed - Random seed for initial positions
+ * @returns {Object} Positions dictionary keyed by node
+ */
+export function fruchtermanReingoldLayout(
+  G: Graph,
+  k: number | null = null,
+  pos: PositionMap | null = null,
+  fixed: Node[] | null = null,
+  iterations: number = 50,
+  scale: number = 1,
+  center: number[] | null = null,
+  dim: number = 2,
+  seed: number | null = null
+): PositionMap {
+  const processed = _processParams(G, center, dim);
+  let graph = processed.G;
+  center = processed.center;
+
+  const nodes = getNodesFromGraph(graph);
+  const edges = getEdgesFromGraph(graph);
+
+  if (nodes.length === 0) {
+    return {};
+  }
+
+  if (nodes.length === 1) {
+    const singlePos: PositionMap = {};
+    singlePos[nodes[0]] = center;
+    return singlePos;
+  }
+
+  // Set up initial positions
+  let positions: PositionMap = {};
+  if (pos) {
+    // Use provided positions
+    for (const node of nodes) {
+      if (pos[node]) {
+        positions[node] = [...pos[node]];
+      } else {
+        const rng = new RandomNumberGenerator(seed ?? undefined);
+        positions[node] = rng.rand(dim) as number[];
+      }
+    }
+  } else {
+    // Random initial positions
+    const rng = new RandomNumberGenerator(seed ?? undefined);
+    for (const node of nodes) {
+      positions[node] = rng.rand(dim) as number[];
+    }
+  }
+
+  // Set up fixed nodes
+  const fixedNodes = new Set(fixed || []);
+
+  // Optimal distance between nodes
+  if (!k) {
+    k = 1.0 / Math.sqrt(nodes.length);
+  }
+
+  // Initialize temperature
+  let t = 0.1;
+  // Calculate temperature reduction
+  const dt = t / (iterations + 1);
+
+  // Simple cooling schedule
+  for (let i = 0; i < iterations; i++) {
+    // Calculate repulsive forces
+    const displacement: Record<Node, number[]> = {};
+    for (const node of nodes) {
+      displacement[node] = Array(dim).fill(0);
+    }
+
+    // Repulsive forces between nodes
+    for (let v1i = 0; v1i < nodes.length; v1i++) {
+      const v1 = nodes[v1i];
+      for (let v2i = v1i + 1; v2i < nodes.length; v2i++) {
+        const v2 = nodes[v2i];
+
+        // Difference vector
+        const delta = positions[v1].map((p, i) => p - positions[v2][i]);
+
+        // Distance
+        const distance = Math.sqrt(delta.reduce((sum, d) => sum + d * d, 0)) || 0.1;
+
+        // Force
+        const force = (k * k) / distance;
+
+        // Add force to displacement
+        for (let j = 0; j < dim; j++) {
+          const direction = delta[j] / distance;
+          displacement[v1][j] += direction * force;
+          displacement[v2][j] -= direction * force;
+        }
+      }
+    }
+
+    // Attractive forces between connected nodes
+    for (const [source, target] of edges) {
+      // Difference vector
+      const delta = positions[source].map((p, i) => p - positions[target][i]);
+
+      // Distance
+      const distance = Math.sqrt(delta.reduce((sum, d) => sum + d * d, 0)) || 0.1;
+
+      // Force
+      const force = (distance * distance) / k;
+
+      // Add force to displacement
+      for (let j = 0; j < dim; j++) {
+        const direction = delta[j] / distance;
+        displacement[source][j] -= direction * force;
+        displacement[target][j] += direction * force;
+      }
+    }
+
+    // Update positions
+    for (const node of nodes) {
+      if (fixedNodes.has(node)) continue;
+
+      // Calculate displacement magnitude
+      const magnitude = Math.sqrt(displacement[node].reduce((sum, d) => sum + d * d, 0));
+
+      // Limit maximum displacement by temperature
+      const limitedMagnitude = Math.min(magnitude, t);
+
+      // Update position
+      for (let j = 0; j < dim; j++) {
+        const direction = magnitude === 0 ? 0 : displacement[node][j] / magnitude;
+        positions[node][j] += direction * limitedMagnitude;
+      }
+    }
+
+    // Cool temperature
+    t -= dt;
+  }
+
+  // Rescale positions
+  if (!fixed) {
+    positions = rescaleLayout(positions, scale, center) as PositionMap;
+  }
+
+  return positions;
+}

package/src/layouts/force-directed/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Force-directed layout algorithms
+ */
+
+export { springLayout } from './spring';
+export { fruchtermanReingoldLayout } from './fruchterman-reingold';
+export { kamadaKawaiLayout } from './kamada-kawai';
+export { forceatlas2Layout } from './forceatlas2';
+export { arfLayout } from './arf';

package/src/layouts/force-directed/kamada-kawai.ts

@@ -0,0 +1,112 @@
+import type { Graph, Node, PositionMap } from '../../types';
+import type { DistanceMap } from '../../algorithms/optimization';
+import { getNodesFromGraph } from '../../utils/graph';
+import { _processParams } from '../../utils/params';
+import { rescaleLayout } from '../../utils/rescale';
+import { circularLayout } from '../geometric/circular';
+import { 
+  _computeShortestPathDistances,
+  _kamadaKawaiSolve
+} from '../../algorithms/optimization';
+
+/**
+ * Position nodes using Kamada-Kawai path-length cost-function.
+ * 
+ * @param G - NetworkX graph or list of nodes
+ * @param dist - A two-level dictionary of optimal distances between nodes
+ * @param pos - Initial positions for nodes
+ * @param weight - The edge attribute used for edge weights
+ * @param scale - Scale factor for positions
+ * @param center - Coordinate pair around which to center the layout
+ * @param dim - Dimension of layout
+ * @returns Positions dictionary keyed by node
+ */
+export function kamadaKawaiLayout(
+  G: Graph,
+  dist: DistanceMap | null = null,
+  pos: PositionMap | null = null,
+  weight: string = 'weight',
+  scale: number = 1,
+  center: number[] | null = null,
+  dim: number = 2
+): PositionMap {
+  const processed = _processParams(G, center, dim);
+  const graph = processed.G;
+  center = processed.center;
+
+  const nodes = getNodesFromGraph(graph);
+
+  if (nodes.length === 0) {
+    return {};
+  }
+
+  if (nodes.length === 1) {
+    return { [nodes[0]]: center };
+  }
+
+  // Initialize distance matrix
+  if (!dist) {
+    // Kamada-Kawai requires a proper Graph, not just a list of nodes
+    if (Array.isArray(graph)) {
+      throw new Error('Kamada-Kawai layout requires a Graph with edges, not just a list of nodes');
+    }
+    dist = _computeShortestPathDistances(graph, weight);
+  }
+
+  // Convert distances to a matrix
+  const nodesArray: Node[] = Array.from(nodes);
+  const nNodes = nodesArray.length;
+  const distMatrix: number[][] = Array(nNodes).fill(0).map(() => Array(nNodes).fill(1e6));
+
+  for (let i = 0; i < nNodes; i++) {
+    const nodeI = nodesArray[i];
+    distMatrix[i][i] = 0;
+
+    if (!dist[nodeI]) continue;
+
+    for (let j = 0; j < nNodes; j++) {
+      const nodeJ = nodesArray[j];
+      if (dist[nodeI][nodeJ] !== undefined) {
+        distMatrix[i][j] = dist[nodeI][nodeJ];
+      }
+    }
+  }
+
+  // Initialize positions if not provided
+  if (!pos) {
+    if (dim >= 2) {
+      // Use circular/spherical layout for 2D and 3D
+      pos = circularLayout(G, 1, center, dim);
+    } else {
+      // For 1D, use a linear layout
+      const posArray: PositionMap = {};
+      nodesArray.forEach((node, i) => {
+        posArray[node] = [i / (nNodes - 1 || 1)];
+      });
+      pos = posArray;
+    }
+  }
+
+  // Convert positions to array for computation
+  const posArray: number[][] = new Array(nNodes);
+  for (let i = 0; i < nNodes; i++) {
+    const node = nodesArray[i];
+    posArray[i] = pos[node] ? [...pos[node]] : Array(dim).fill(0);
+
+    // Ensure correct dimensionality
+    while (posArray[i].length < dim) {
+      posArray[i].push(0);
+    }
+  }
+
+  // Run the Kamada-Kawai algorithm
+  const newPositions = _kamadaKawaiSolve(distMatrix, posArray, dim);
+
+  // Convert positions array back to dictionary and rescale
+  const finalPos: PositionMap = {};
+  for (let i = 0; i < nNodes; i++) {
+    finalPos[nodesArray[i]] = newPositions[i];
+  }
+
+  return rescaleLayout(finalPos, scale, center) as PositionMap;
+}