@graphty/layout 1.2.0 → 1.2.2

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

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

@@ -0,0 +1,35 @@
+/**
+ * Spring layout algorithm (Fruchterman-Reingold variant)
+ */
+
+import { Graph, Node, PositionMap } from '../../types';
+import { fruchtermanReingoldLayout } from './fruchterman-reingold';
+
+/**
+ * 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 springLayout(
+  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 {
+  // Legacy compatibility alias
+  return fruchtermanReingoldLayout(G, k, pos, fixed, iterations, scale, center, dim, seed);
+}

package/src/layouts/geometric/circular.ts

@@ -0,0 +1,77 @@
+/**
+ * Circular layout algorithm
+ */
+
+import { Graph, Node, PositionMap } from '../../types';
+import { _processParams } from '../../utils/params';
+import { getNodesFromGraph } from '../../utils/graph';
+import { RandomNumberGenerator } from '../../utils/random';
+import { np } from '../../utils/numpy';
+
+/**
+ * Position nodes on a circle (2D) or sphere (3D).
+ * 
+ * @param G - Graph or list of nodes
+ * @param scale - Scale factor for positions
+ * @param center - Coordinate pair around which to center the layout
+ * @param dim - Dimension of layout (supports 2D circle or 3D sphere)
+ * @returns Positions dictionary keyed by node
+ */
+export function circularLayout(G: Graph, scale: number = 1, center: number[] | null = null, dim: number = 2): PositionMap {
+  if (dim < 2) {
+    throw new Error("cannot handle dimensions < 2");
+  }
+
+  const processed = _processParams(G, center, dim);
+  const nodes = getNodesFromGraph(processed.G);
+  center = processed.center;
+
+  const pos: PositionMap = {};
+
+  if (nodes.length === 0) {
+    return pos;
+  }
+
+  if (nodes.length === 1) {
+    pos[nodes[0]] = center;
+    return pos;
+  }
+
+  if (dim === 2) {
+    // 2D circle layout
+    const theta = np.linspace(0, 2 * Math.PI, nodes.length + 1).slice(0, -1);
+
+    nodes.forEach((node: Node, i: number) => {
+      const x: number = Math.cos(theta[i]) * scale + center[0];
+      const y: number = Math.sin(theta[i]) * scale + center[1];
+      pos[node] = [x, y];
+    });
+  } else if (dim === 3) {
+    // 3D sphere layout using Fibonacci spiral
+    const n = nodes.length;
+    const goldenRatio = (1 + Math.sqrt(5)) / 2;
+    
+    nodes.forEach((node: Node, i: number) => {
+      // Use Fibonacci spiral for even distribution on sphere
+      const theta = 2 * Math.PI * i / goldenRatio;
+      const phi = Math.acos(1 - 2 * (i + 0.5) / n);
+      
+      const x = Math.sin(phi) * Math.cos(theta) * scale + center[0];
+      const y = Math.sin(phi) * Math.sin(theta) * scale + center[1];
+      const z = Math.cos(phi) * scale + center[2];
+      
+      pos[node] = [x, y, z];
+    });
+  } else {
+    // For higher dimensions, fall back to random on hypersphere
+    const rng = new RandomNumberGenerator();
+    nodes.forEach((node: Node) => {
+      // Generate random point on unit hypersphere
+      const coords = Array(dim).fill(0).map(() => rng.rand() as number * 2 - 1);
+      const norm = Math.sqrt(coords.reduce((sum, c) => sum + c * c, 0));
+      pos[node] = coords.map((c, j) => c / norm * scale + center[j]);
+    });
+  }
+
+  return pos;
+}

package/src/layouts/geometric/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Geometric layout algorithms
+ */
+
+export { circularLayout } from './circular';
+export { shellLayout } from './shell';
+export { spiralLayout } from './spiral';

package/src/layouts/geometric/shell.ts

@@ -0,0 +1,80 @@
+/**
+ * Shell layout algorithm
+ */
+
+import { Graph, Node, PositionMap } from '../../types';
+import { _processParams } from '../../utils/params';
+import { getNodesFromGraph } from '../../utils/graph';
+import { np } from '../../utils/numpy';
+
+/**
+ * Position nodes in concentric circles.
+ * 
+ * @param G - Graph or list of nodes
+ * @param nlist - List of node lists for each shell
+ * @param scale - Scale factor for positions
+ * @param center - Coordinate pair around which to center the layout
+ * @param dim - Dimension of layout (currently only supports dim=2)
+ * @returns Positions dictionary keyed by node
+ */
+export function shellLayout(G: Graph, nlist: Node[][] | null = null, scale: number = 1, center: number[] | null = null, dim: number = 2): PositionMap {
+  if (dim !== 2) {
+    throw new Error("can only handle 2 dimensions");
+  }
+
+  const processed = _processParams(G, center, dim);
+  const nodes = getNodesFromGraph(processed.G);
+  center = processed.center;
+
+  const pos: PositionMap = {};
+
+  if (nodes.length === 0) {
+    return pos;
+  }
+
+  if (nodes.length === 1) {
+    pos[nodes[0]] = center;
+    return pos;
+  }
+
+  // If no nlist is specified, put all nodes in a single shell
+  if (!nlist) {
+    nlist = [nodes];
+  }
+
+  const radiusBump = scale / nlist.length;
+  let radius: number;
+
+  if (nlist[0].length === 1) {
+    // Single node at center
+    radius = 0;
+    pos[nlist[0][0]] = [...center];
+    radius += radiusBump;
+  } else {
+    // Start at radius 1
+    radius = radiusBump;
+  }
+
+  for (let i = 0; i < nlist.length; i++) {
+    const shell = nlist[i];
+    if (shell.length === 0) continue;
+
+    if (shell.length === 1 && i === 0) {
+      // Already handled the case of a single center node
+      continue;
+    }
+
+    // Calculate positions on a circle
+    const theta = np.linspace(0, 2 * Math.PI, shell.length + 1).slice(0, -1);
+
+    shell.forEach((node: Node, j) => {
+      const x = Math.cos(theta[j]) * radius + center[0];
+      const y = Math.sin(theta[j]) * radius + center[1];
+      pos[node] = [x, y];
+    });
+
+    radius += radiusBump;
+  }
+
+  return pos;
+}

package/src/layouts/geometric/spiral.ts

@@ -0,0 +1,93 @@
+/**
+ * Spiral layout algorithm
+ */
+
+import { Graph, Node, PositionMap } from '../../types';
+import { _processParams } from '../../utils/params';
+import { getNodesFromGraph } from '../../utils/graph';
+import { rescaleLayout } from '../../utils/rescale';
+
+/**
+ * Position nodes in a spiral layout.
+ * 
+ * @param G - Graph or list of nodes
+ * @param scale - Scale factor for positions
+ * @param center - Coordinate pair around which to center the layout
+ * @param dim - Dimension of layout
+ * @param resolution - Controls the spacing between spiral elements
+ * @param equidistant - Whether to place nodes equidistant from each other
+ * @returns Positions dictionary keyed by node
+ */
+export function spiralLayout(
+  G: Graph,
+  scale: number = 1,
+  center: number[] | null = null,
+  dim: number = 2,
+  resolution: number = 0.35,
+  equidistant: boolean = false
+): PositionMap {
+  if (dim !== 2) {
+    throw new Error("can only handle 2 dimensions");
+  }
+
+  const processed = _processParams(G, center || [0, 0], dim);
+  const nodes = getNodesFromGraph(processed.G);
+  center = processed.center;
+
+  const pos: PositionMap = {};
+
+  if (nodes.length === 0) {
+    return pos;
+  }
+
+  if (nodes.length === 1) {
+    pos[nodes[0]] = [...center];
+    return pos;
+  }
+
+  let positions: number[][] = [];
+
+  if (equidistant) {
+    // Create equidistant points along the spiral
+    // This matches the Python implementation logic
+    const chord = 1;
+    const step = 0.5;
+    let theta = resolution;
+    theta += chord / (step * theta);
+
+    for (let i = 0; i < nodes.length; i++) {
+      const r = step * theta;
+      theta += chord / r;
+      positions.push([Math.cos(theta) * r, Math.sin(theta) * r]);
+    }
+  } else {
+    // Create points with equal angle but increasing distance
+    const dist = Array.from({ length: nodes.length }, (_, i) => parseFloat(String(i)));
+    const angle = dist.map(d => resolution * d);
+
+    positions = dist.map((d, i) => [
+      Math.cos(angle[i]) * d,
+      Math.sin(angle[i]) * d
+    ]);
+  }
+
+  // Convert position array to position matrix for rescaling
+  const posArray: number[][] = [];
+  for (let i = 0; i < positions.length; i++) {
+    posArray.push(positions[i]);
+  }
+
+  // Rescale positions and add center offset
+  const scaledPositions = rescaleLayout(posArray as any, scale) as any;
+  for (let i = 0; i < scaledPositions.length; i++) {
+    scaledPositions[i][0] += center[0];
+    scaledPositions[i][1] += center[1];
+  }
+
+  // Create position dictionary
+  for (let i = 0; i < nodes.length; i++) {
+    pos[nodes[i]] = scaledPositions[i];
+  }
+
+  return pos;
+}

package/src/layouts/hierarchical/bfs.ts

@@ -0,0 +1,81 @@
+import type { Graph, Node, Edge, PositionMap } from '../../types';
+import { getNodesFromGraph, getNeighbors } from '../../utils/graph';
+import { _processParams } from '../../utils/params';
+import { multipartiteLayout } from './multipartite';
+
+/**
+ * Position nodes according to breadth-first search algorithm.
+ * 
+ * @param G - Graph 
+ * @param start - Starting node for bfs
+ * @param align - The alignment of layers: 'vertical' or 'horizontal'
+ * @param scale - Scale factor for positions
+ * @param center - Coordinate pair around which to center the layout
+ * @returns Positions dictionary keyed by node
+ */
+export function bfsLayout(
+  G: Graph,
+  start: Node,
+  align: 'vertical' | 'horizontal' = 'vertical',
+  scale: number = 1,
+  center: number[] | null = null
+): PositionMap {
+  const processed = _processParams(G, center || [0, 0], 2);
+  
+  // BFS layout requires a proper Graph, not just a list of nodes
+  if (Array.isArray(processed.G)) {
+    throw new Error('BFS layout requires a Graph with edges, not just a list of nodes');
+  }
+  
+  const graph = processed.G;
+  center = processed.center;
+
+  const allNodes = getNodesFromGraph(graph);
+
+  if (allNodes.length === 0) {
+    return {};
+  }
+
+  // Compute BFS layers
+  const layers: Record<number, Node[]> = {};
+  const visited = new Set<Node>();
+  let currentLayer = 0;
+
+  // Starting layer
+  layers[currentLayer] = [start];
+  visited.add(start);
+
+  // BFS traversal
+  while (Object.values(layers).flat().length < allNodes.length) {
+    const nextLayer: Node[] = [];
+    const currentNodes = layers[currentLayer];
+
+    for (const node of currentNodes) {
+      // Get neighbors - this is a simplified approach
+      // In a real implementation, we would get neighbors from the graph
+      const neighbors = getNeighbors(graph, node);
+
+      for (const neighbor of neighbors) {
+        if (!visited.has(neighbor)) {
+          nextLayer.push(neighbor);
+          visited.add(neighbor);
+        }
+      }
+    }
+
+    if (nextLayer.length === 0) {
+      // No more connected nodes
+      const unvisited: Node[] = allNodes.filter((node: Node) => !visited.has(node));
+      if (unvisited.length > 0) {
+        throw new Error("bfs_layout didn't include all nodes. Graph may be disconnected.");
+      }
+      break;
+    }
+
+    currentLayer++;
+    layers[currentLayer] = nextLayer;
+  }
+
+  // Use multipartite_layout to position the layers
+  return multipartiteLayout(graph, layers, align, scale, center);
+}