@graphty/layout 1.1.1 → 1.2.1

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

package/src/layouts/hierarchical/bipartite.ts

@@ -0,0 +1,94 @@
+/**
+ * Bipartite 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 two straight lines (bipartite layout).
+ * 
+ * @param G - Graph or list of nodes
+ * @param nodes - Nodes in one node set of the graph
+ * @param align - The alignment of nodes: 'vertical' or 'horizontal'
+ * @param scale - Scale factor for positions
+ * @param center - Coordinate pair around which to center the layout
+ * @param aspectRatio - The ratio of the width to the height of the layout
+ * @returns Positions dictionary keyed by node
+ */
+export function bipartiteLayout(
+  G: Graph,
+  nodes: Node[] | null = null,
+  align: 'vertical' | 'horizontal' = 'vertical',
+  scale: number = 1,
+  center: number[] | null = null,
+  aspectRatio: number = 4 / 3
+): PositionMap {
+  if (align !== 'vertical' && align !== 'horizontal') {
+    throw new Error("align must be either vertical or horizontal");
+  }
+
+  const processed = _processParams(G, center || [0, 0], 2);
+  const graph = processed.G;
+  center = processed.center;
+
+  const allNodes = getNodesFromGraph(graph);
+
+  if (allNodes.length === 0) {
+    return {};
+  }
+
+  // If nodes not provided, try to determine bipartite sets
+  if (!nodes) {
+    // A simple heuristic for bipartite detection: use nodes with even/odd indices
+    // This is a simplification, in Python NetworkX has bipartite.sets()
+    nodes = allNodes.filter((_: Node, i: number): boolean => i % 2 === 0);
+  }
+
+  const left = new Set(nodes);
+  const right: Set<Node> = new Set(allNodes.filter((n: Node) => !left.has(n)));
+
+  const height = 1;
+  const width = aspectRatio * height;
+  const offset = [width / 2, height / 2];
+
+  const pos: PositionMap = {};
+
+  // Position nodes in the left set
+  const leftNodes = [...left];
+  leftNodes.forEach((node, i) => {
+    const x = 0;
+    const y = i * height / (leftNodes.length || 1);
+    pos[node] = [x, y];
+  });
+
+  // Position nodes in the right set
+  const rightNodes = [...right];
+  rightNodes.forEach((node, i) => {
+    const x = width;
+    const y = i * height / (rightNodes.length || 1);
+    pos[node] = [x, y];
+  });
+
+  // Center positions around the origin and apply offset
+  for (const node in pos) {
+    pos[node][0] -= offset[0];
+    pos[node][1] -= offset[1];
+  }
+
+  // Rescale positions
+  const scaledPos = rescaleLayout(pos, scale, center) as PositionMap;
+
+  // Handle horizontal alignment
+  if (align === 'horizontal') {
+    for (const node in scaledPos) {
+      const temp = scaledPos[node][0];
+      scaledPos[node][0] = scaledPos[node][1];
+      scaledPos[node][1] = temp;
+    }
+  }
+
+  return scaledPos;
+}

package/src/layouts/hierarchical/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Hierarchical layout algorithms
+ */
+
+export { bipartiteLayout } from './bipartite';
+export { multipartiteLayout } from './multipartite';
+export { bfsLayout } from './bfs';

package/src/layouts/hierarchical/multipartite.ts

@@ -0,0 +1,88 @@
+import type { Graph, Node, PositionMap } from '../../types';
+import { getNodesFromGraph, getNeighbors } from '../../utils/graph';
+import { _processParams } from '../../utils/params';
+import { rescaleLayout } from '../../utils/rescale';
+
+/**
+ * Position nodes in layers of straight lines (multipartite layout).
+ * 
+ * @param G - Graph or list of nodes
+ * @param subsetKey - Object mapping layers to node sets, or node attribute name
+ * @param align - The alignment of nodes: '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 multipartiteLayout(
+  G: Graph,
+  subsetKey: Record<number | string, Node | Node[]> | string = 'subset',
+  align: 'vertical' | 'horizontal' = 'vertical',
+  scale: number = 1,
+  center: number[] | null = null
+): PositionMap {
+  if (align !== 'vertical' && align !== 'horizontal') {
+    throw new Error("align must be either vertical or horizontal");
+  }
+
+  const processed = _processParams(G, center || [0, 0], 2);
+  const graph = processed.G;
+  center = processed.center;
+
+  const allNodes = getNodesFromGraph(graph);
+
+  if (allNodes.length === 0) {
+    return {};
+  }
+
+  // Convert subsetKey to a layer mapping if it's a string
+  let layers: Record<number | string, Node[]> = {};
+  if (typeof subsetKey === 'string') {
+    // In JS we don't have access to node attributes directly
+    // This is a simplification - in a real implementation we would need
+    // to access node attributes from the graph
+    console.warn("Using string subsetKey requires node attributes, using default partitioning");
+    // Create a simple partitioning as fallback
+    layers = { 0: allNodes };
+  } else {
+    // subsetKey is already a mapping of layers to nodes
+    // Convert single nodes to arrays
+    for (const [key, value] of Object.entries(subsetKey)) {
+      if (Array.isArray(value)) {
+        layers[key] = value;
+      } else {
+        layers[key] = [value];
+      }
+    }
+  }
+
+  const layerCount = Object.keys(layers).length;
+  let pos: PositionMap = {};
+
+  // Process each layer
+  Object.entries(layers).forEach(([layer, nodes], layerIdx) => {
+    const layerNodes = Array.isArray(nodes) ? nodes : [nodes];
+    const layerSize = layerNodes.length;
+
+    layerNodes.forEach((node, nodeIdx) => {
+      // Place nodes in a grid: layerIdx determines x-coordinate (column)
+      // nodeIdx determines y-coordinate (row position within column)
+      const x = layerIdx - (layerCount - 1) / 2;
+      const y = nodeIdx - (layerSize - 1) / 2;
+      pos[node] = [x, y];
+    });
+  });
+
+  // Rescale positions
+  pos = rescaleLayout(pos, scale, center) as PositionMap;
+
+  // Handle horizontal alignment
+  if (align === 'horizontal') {
+    for (const node in pos) {
+      const temp = pos[node][0];
+      pos[node][0] = pos[node][1];
+      pos[node][1] = temp;
+    }
+  }
+
+  return pos;
+}

package/src/layouts/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Re-export all layout algorithms
+ */
+
+export * from './basic';
+export * from './geometric';
+export * from './force-directed';
+export * from './hierarchical';
+export * from './specialized';

package/src/layouts/specialized/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Specialized layout algorithms
+ */
+
+export { spectralLayout } from './spectral';
+export { planarLayout } from './planar';

package/src/layouts/specialized/planar.ts

@@ -0,0 +1,65 @@
+/**
+ * Planar layout algorithm
+ */
+
+import { Graph, Node, Edge, PositionMap } from '../../types';
+import { _processParams } from '../../utils/params';
+import { getNodesFromGraph, getEdgesFromGraph } from '../../utils/graph';
+import { rescaleLayout } from '../../utils/rescale';
+import { checkPlanarity, combinatorialEmbeddingToPos } from '../../algorithms/planarity';
+
+/**
+ * Position nodes without edge intersections (planar layout).
+ * 
+ * @param G - Graph
+ * @param scale - Scale factor for positions
+ * @param center - Coordinate pair around which to center the layout
+ * @param dim - Dimension of layout (must be 2)
+ * @returns Positions dictionary keyed by node
+ */
+export function planarLayout(
+  G: Graph,
+  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 || [0, 0], dim);
+  
+  // Planar layout requires a proper Graph, not just a list of nodes
+  if (Array.isArray(processed.G)) {
+    throw new Error('Planar layout requires a Graph with edges, not just a list of nodes');
+  }
+  
+  const graph = processed.G;
+  center = processed.center;
+
+  const nodes = getNodesFromGraph(graph);
+  const edges = getEdgesFromGraph(graph);
+
+  if (nodes.length === 0) {
+    return {};
+  }
+
+  // Check if graph is planar and get embedding
+  const { isPlanar, embedding } = checkPlanarity(graph, nodes, edges);
+
+  if (!isPlanar) {
+    throw new Error("G is not planar.");
+  }
+
+  if (!embedding) {
+    throw new Error("Failed to generate planar embedding.");
+  }
+
+  // Convert embedding to positions
+  let pos = combinatorialEmbeddingToPos(embedding, nodes);
+
+  // Rescale the positions
+  pos = rescaleLayout(pos, scale, center) as PositionMap;
+
+  return pos;
+}