@graphty/layout 1.2.0 → 1.2.1

package/src/generators/scale-free.ts

@@ -0,0 +1,72 @@
+/**
+ * Scale-free graph generation function
+ */
+
+import { Graph, Node, Edge } from '../types';
+
+/**
+ * Create a scale-free graph using Barabási-Albert model
+ * @param n - Total number of nodes
+ * @param m - Number of edges to attach from new node
+ * @param seed - Random seed for reproducibility
+ * @returns Graph object with scale-free properties
+ */
+export function scaleFreeGraph(n: number, m: number, seed?: number): Graph {
+  if (m >= n) {
+    throw new Error('m must be less than n');
+  }
+  
+  const nodes: Node[] = Array.from({ length: n }, (_, i) => i);
+  const edges: Edge[] = [];
+  const degrees = new Array(n).fill(0);
+  
+  // Simple deterministic pseudo-random if seed provided
+  let currentSeed = seed;
+  let random = seed !== undefined 
+    ? () => {
+        currentSeed = (currentSeed! * 9301 + 49297) % 233280;
+        return currentSeed / 233280;
+      }
+    : Math.random;
+  
+  // Start with complete graph of m+1 nodes
+  for (let i = 0; i <= m; i++) {
+    for (let j = i + 1; j <= m; j++) {
+      edges.push([i, j]);
+      degrees[i]++;
+      degrees[j]++;
+    }
+  }
+  
+  // Add remaining nodes
+  for (let i = m + 1; i < n; i++) {
+    const targets = new Set<number>();
+    const totalDegree = degrees.reduce((sum, d) => sum + d, 0);
+    
+    // Choose m targets based on preferential attachment
+    while (targets.size < m) {
+      let r = random() * totalDegree;
+      let cumSum = 0;
+      
+      for (let j = 0; j < i; j++) {
+        cumSum += degrees[j];
+        if (r <= cumSum && !targets.has(j)) {
+          targets.add(j);
+          break;
+        }
+      }
+    }
+    
+    // Add edges to targets
+    for (const target of targets) {
+      edges.push([i, target]);
+      degrees[i]++;
+      degrees[target]++;
+    }
+  }
+  
+  return {
+    nodes: () => nodes,
+    edges: () => edges
+  };
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Main entry point for @graphty/layout
+ * 
+ * This file exports the complete public API, maintaining
+ * compatibility with the original layout.ts file.
+ */
+
+// Re-export all types
+export * from './types';
+
+// Re-export utilities that are part of the public API
+export { rescaleLayout, rescaleLayoutDict } from './utils/rescale';
+
+// Re-export all layout algorithms
+export * from './layouts';
+
+// Re-export all graph generation functions
+export * from './generators';

package/src/layouts/basic/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Basic layout algorithms
+ */
+
+export { randomLayout } from './random';

package/src/layouts/basic/random.ts

@@ -0,0 +1,32 @@
+/**
+ * Random layout algorithm
+ */
+
+import { Graph, Node, PositionMap } from '../../types';
+import { _processParams } from '../../utils/params';
+import { getNodesFromGraph } from '../../utils/graph';
+import { RandomNumberGenerator } from '../../utils/random';
+
+/**
+ * Position nodes uniformly at random in the unit square.
+ * 
+ * @param G - Graph or list of nodes
+ * @param center - Coordinate pair around which to center the layout
+ * @param dim - Dimension of layout
+ * @param seed - Random seed for reproducible layouts
+ * @returns Positions dictionary keyed by node
+ */
+export function randomLayout(G: Graph | Node[], center: number[] | null = null, dim: number = 2, seed: number | null = null): PositionMap {
+  const processed = _processParams(G, center, dim);
+  const nodes = getNodesFromGraph(processed.G);
+  center = processed.center;
+
+  const rng = new RandomNumberGenerator(seed ?? undefined);
+  const pos: PositionMap = {};
+
+  nodes.forEach((node: Node) => {
+    pos[node] = (rng.rand(dim) as number[]).map((val: number, i: number) => val + center[i]);
+  });
+
+  return pos;
+}

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

@@ -0,0 +1,130 @@
+import type { Graph, Node, PositionMap } from '../../types';
+import { getNodesFromGraph, getEdgesFromGraph } from '../../utils/graph';
+import { RandomNumberGenerator } from '../../utils/random';
+import { randomLayout } from '../basic/random';
+
+/**
+ * Layout algorithm with attractive and repulsive forces (ARF).
+ * 
+ * @param G - Graph
+ * @param pos - Initial positions for nodes
+ * @param scaling - Scale factor for positions
+ * @param a - Strength of springs between connected nodes (should be > 1)
+ * @param maxIter - Maximum number of iterations
+ * @param seed - Random seed for initial positions
+ * @returns Positions dictionary keyed by node
+ */
+export function arfLayout(
+  G: Graph,
+  pos: PositionMap | null = null,
+  scaling: number = 1,
+  a: number = 1.1,
+  maxIter: number = 1000,
+  seed: number | null = null
+): PositionMap {
+  if (a <= 1) {
+    throw new Error("The parameter a should be larger than 1");
+  }
+
+  const nodes = getNodesFromGraph(G);
+  const edges = getEdgesFromGraph(G);
+
+  if (nodes.length === 0) {
+    return {};
+  }
+
+  // Initialize positions if not provided
+  if (!pos) {
+    pos = randomLayout(G, null, 2, seed);
+  } else {
+    // Make sure all nodes have positions
+    const rng = new RandomNumberGenerator(seed ?? undefined);
+    const defaultPos: PositionMap = {};
+    nodes.forEach((node: Node) => {
+      if (!pos![node]) {
+        defaultPos[node] = [(rng.rand() as number), (rng.rand() as number)];
+      }
+    });
+    pos = { ...pos, ...defaultPos };
+  }
+
+  // Create node index mapping
+  const nodeIndex: Record<Node, number> = {};
+  nodes.forEach((node: Node, i: number) => {
+    nodeIndex[node] = i;
+  });
+
+  // Create positions array
+  const positions: number[][] = nodes.map((node: Node) => [...pos![node]]);
+
+  // Initialize spring constant matrix
+  const N = nodes.length;
+  const K = Array(N).fill(0).map(() => Array(N).fill(1));
+
+  // Set diagonal to zero (no self-attraction)
+  for (let i = 0; i < N; i++) {
+    K[i][i] = 0;
+  }
+
+  // Set stronger attraction between connected nodes
+  for (const [source, target] of edges) {
+    if (source === target) continue;
+
+    const i = nodeIndex[source];
+    const j = nodeIndex[target];
+    K[i][j] = a;
+    K[j][i] = a;
+  }
+
+  // Calculate rho (scale factor)
+  const rho = scaling * Math.sqrt(N);
+
+  // Optimization loop
+  const dt = 1e-3;  // Time step
+  const etol = 1e-6;  // Error tolerance
+  let error = etol + 1;
+  let nIter = 0;
+
+  while (error > etol && nIter < maxIter) {
+    // Calculate changes for each node
+    const change = Array(N).fill(0).map(() => [0, 0]);
+
+    for (let i = 0; i < N; i++) {
+      for (let j = 0; j < N; j++) {
+        if (i === j) continue;
+
+        // Calculate difference vector
+        const diff = positions[i].map((coord, dim) => coord - positions[j][dim]);
+
+        // Calculate distance (with minimum to avoid division by zero)
+        const dist = Math.sqrt(diff.reduce((sum, d) => sum + d * d, 0)) || 0.01;
+
+        // Calculate attractive and repulsive forces
+        for (let d = 0; d < diff.length; d++) {
+          change[i][d] += K[i][j] * diff[d] - (rho / dist) * diff[d];
+        }
+      }
+    }
+
+    // Update positions
+    for (let i = 0; i < N; i++) {
+      for (let d = 0; d < positions[i].length; d++) {
+        positions[i][d] += change[i][d] * dt;
+      }
+    }
+
+    // Calculate error (sum of force magnitudes)
+    error = change.reduce((sum, c) =>
+      sum + Math.sqrt(c.reduce((s, v) => s + v * v, 0)), 0);
+
+    nIter++;
+  }
+
+  // Convert positions array back to object
+  const finalPos: PositionMap = {};
+  nodes.forEach((node: Node, i: number) => {
+    finalPos[node] = positions[i];
+  });
+
+  return finalPos;
+}

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;
+}