@davidsouther/agathon 0.0.0-stage → 2026.11.1

package/src/layout/hierarchic/rank.ts

@@ -0,0 +1,629 @@
+import { assert, assertExists, assertFinite } from "../../assert.ts";
+import { dfs, Order } from "../../tsabre/algo.ts";
+import { edgeId, TsabreGraph } from "../../tsabre/graph.ts";
+import type { Edge, FullGraph, Node, NodeId } from "../../types.ts";
+import type { LayoutEdge, LayoutNode, NodeProperties } from "../types.ts";
+import * as util from "../util.ts";
+
+import * as debug from "./debug.ts";
+
+/**
+ * Ranking a graph is the process of assigning a vertical position to each node
+ * in the graph, such that all successors of a node have a higher rank than
+ * itself. There are many feasible rankings which satisfy this criteria, so
+ * by applying principal A3 "Short edges" in Layout, there is an additional
+ * constraint to minimize weighted edges lengths. This is more than an aesthetic
+ * concern, however, as many later passes (especially in ordering) are runtime
+ * sensitive to the number of ranks in the graph.
+ *
+ * The constraint that all successors have a higher rank additionally implies an
+ * acyclic graph. Therefore, the first step in ranking is to remove cycles. This
+ * is achieved by finding the "Feedback Arc Set", a known problem in graph
+ * literature. See the implementation & notes in acyclic.ts. Further
+ * optimizaztions come by nesting multiple edges between pairs of nodes into a
+ * single edge with a summed weight.
+ *
+ * By reformulating this constraint as a numerical optimization problem,
+ * well-known network simplex algorithms solve the problem quickly and
+ * effectively. Finally, the graph is renormalized so that the lowest rank is 0.
+ *
+ * This implementation follows sections 2.2-2.4 of [Gansner], see docs/tsabre for
+ * links.
+ */
+export function rank(g: FullGraph): void {
+  nesting.run(g);
+  networkSimplex(g);
+  removeEmptyRanks(g);
+  nesting.undo(g);
+  normalizeRanks(g);
+}
+
+/**
+ * Run a network simplex optimization on a graph, assigning an optimal rank to
+ * every node. This proceeds by creating an initial feasible tree† and then
+ * exchanging edges from the spanning tree with shorter edges from the graph.
+ * The exchange happens between the tree edge with the most negative "cut
+ * value", and exchanges it with the edge in the graph having the least "slack"
+ * which can connect the two halves of the tree. "Slack" is the difference
+ * between current length and minimum length. The loop terminates when either no
+ * edge in the tree has a negative cut value, or when no edge in the graph could
+ * reconnect the halves.
+ *
+ * † Feasible Tree is a subset of the edges in the graph such that all nodes are
+ * present and reachable as a tree.
+ */
+function networkSimplex(g: FullGraph): void {
+  const { printDebug } = util.getGraphProps(g);
+  g = simplify(g);
+  longestPath(g); // Initialize ranking using longest path.
+  const t = feasibleTree(g);
+  initLowLimValues(t);
+  initCutValues(t, g);
+
+  if (printDebug) console.group("Network Simplex");
+  if (printDebug) debug.printSpanningTree(t);
+  const swaps = new Set<string>();
+
+  let e: Edge | undefined;
+  while ((e = leaveEdge(t))) {
+    const f = enterEdge(t, g, e);
+
+    const eId = edgeId(e);
+    const fId = f !== undefined ? edgeId(f) : "undefined";
+    const id = `${eId} ⇋ ${fId}`;
+
+    if (swaps.has(id)) {
+      debug.print(`network simplex found looping swap with ${id}`);
+      break;
+    }
+    swaps.add(id);
+    if (f === undefined) break;
+
+    exchangeEdges(t, g, e, f);
+  }
+
+  if (printDebug) console.table(swaps);
+  if (printDebug) console.groupEnd();
+}
+
+/**
+ * Given a multigraph (a graph allowing multiple edges between pairs of nodes,
+ * collapse all multiedges updating their minlength and weights.
+ */
+function simplify(graph: FullGraph): FullGraph {
+  const g2 = new TsabreGraph<LayoutNode, LayoutEdge>();
+  const { nestingRoot } = util.getGraphProps(graph);
+  util.getGraphProps(g2).nestingRoot = nestingRoot;
+
+  for (const id of graph.nodes) {
+    g2.setNode(id, graph.node(id)!);
+  }
+  for (const edge of graph.edges()) {
+    const { source, target } = edge;
+    const simple = { source, target };
+    if (!g2.hasEdge(simple)) {
+      g2.setEdge(simple, { ...simple, layout: { weight: 0 } } as LayoutEdge);
+    }
+    const edgeLayout = util.getEdgeProps(graph.edge(edge)!);
+    const layout = util.getEdgeProps(g2.edge(simple)!);
+    layout.weight += edgeLayout.weight;
+    layout.minLength = Math.max(layout.minLength, edgeLayout.minLength);
+  }
+  return g2;
+}
+
+/**
+ * Given a graph, assign a rank to each node such that all successors of a node
+ * have a higher rank than itself. If the node has already been visited, it gets
+ * the first such assignment.
+ */
+function longestPath(g: FullGraph): void {
+  const visited = new Set<NodeId>();
+  function dfs(id: NodeId, minRank = 0): number {
+    const props = util.getNodeProps(g.node(id)!);
+    if (visited.has(id)) {
+      assert(props.rank !== undefined, `${id} visited with no set rank, likely a cycle.`);
+      assert(!isNaN(props.rank), `${id} has rank NaN`);
+      return props.rank;
+    }
+    visited.add(id);
+
+    const ranks = Array.from(g.outEdges(id)).map((edge) => {
+      const { minLength } = util.getEdgeProps(g.edge(edge)!);
+      const childLength = dfs(edge.target, props.fixedRank ? props.rank : 0);
+      return childLength - minLength;
+    });
+
+    const rank = Math.min(...ranks, props.rank || 0) + minRank;
+    setRank(props, rank);
+    return props.rank;
+  }
+
+  for (const id of g.sources) dfs(id);
+}
+
+/**
+ * Adjusts the ranks for all nodes in the graph such that all nodes have
+ * rank >= 0 and at least one node has rank == 0.
+ */
+function normalizeRanks(g: FullGraph): void {
+  const ranks = Array.from(g.allNodes).map((n) => util.getNodeProps(n).rank);
+  const offset = Math.min(...ranks);
+
+  for (const id of g.nodes) {
+    const layout = util.getNodeProps(g.node(id)!);
+    layout.rank -= offset;
+  }
+}
+
+/**
+ * Compact a graph so that there are no ranks with no nodes assigned.
+ */
+export function removeEmptyRanks(g: FullGraph): void {
+  const offset = Math.min(...Array.from(g.nodes).map((id) => util.getNodeProps(g.node(id)!).rank));
+
+  const layers: NodeProperties[][] = [];
+  for (const id of g.nodes) {
+    const layout = util.getNodeProps(g.node(id)!);
+    const rank = layout.rank - offset;
+    layers[rank] = layers[rank] || [];
+    layers[rank].push(layout);
+  }
+
+  let delta = 0;
+  const { nodeRankFactor } = util.getGraphProps(g);
+  for (let i = 0; i < layers.length; i++) {
+    const layer = layers[i];
+    if (layer === undefined && i % nodeRankFactor !== 0) {
+      --delta;
+    } else {
+      for (const layout of layer || []) {
+        layout.rank += delta;
+      }
+    }
+  }
+}
+
+/**
+ * Given a graph, determine an initial feasible spanning tree. Starting from a
+ * longest path, increase rankings of higher-rank nodes until slack on all edges
+ * is non-negative.
+ */
+function feasibleTree(g: FullGraph): TsabreGraph<Node, Edge> {
+  const tree = new TsabreGraph<Node, Edge>({ trackSegments: false });
+
+  const start = Array.from(g.nodes)[0];
+  const size = g.nodeCount;
+
+  tree.setNode(start, { id: start });
+
+  while (tightTree(tree, g) < size) {
+    const edgeSlack = findMinSlackEdge(tree, g);
+    if (!edgeSlack) {
+      break;
+    }
+    const [edge, s] = edgeSlack;
+    const delta = (tree.hasNode(edge.source) ? 1 : -1) * s;
+    shiftRanks(tree, g, delta);
+  }
+
+  return tree;
+}
+
+/**
+ * Given a graph `g` with ranked edges, update `t` to be the subset of `g`
+ * having only edges with slack 0. `t` will be modified in place. Returns the
+ * number of nodes in `t`.
+ */
+function tightTree(t: FullGraph, g: FullGraph): number {
+  for (const id of t.nodes) {
+    findLowSlack(id);
+  }
+  return t.nodeCount;
+
+  function findLowSlack(id: NodeId) {
+    for (const e of g.edges(id)) {
+      const source = e.source;
+      const target = id === source ? e.target : source;
+      const edgeSlack = slack(g, e);
+      if (!t.hasNode(target) && edgeSlack === 0) {
+        t.setNode(target, { id: target });
+        const st = { source: id, target };
+        const ts = { source: target, target: id };
+        t.setEdge(st, st);
+        t.setEdge(ts, ts);
+        findLowSlack(target);
+      }
+    }
+  }
+}
+
+/**
+ * Returns true if an edge connects to but is not entirely in a tree, and false
+ * if both node are in or not in the tree. That is, at least one node must be
+ * in the tree and the other must not be.
+ */
+function incidentEdge(t: FullGraph, e: Edge): boolean {
+  return t.hasNode(e.source) !== t.hasNode(e.target);
+}
+
+/**
+ * Given a partial spanning tree `t` and a graph `g`, an edge in `g` that has
+ * the least slack while also being incident to (only one edge in) `t`. Returns
+ * `undefined` if no such edge exists.
+ */
+function findMinSlackEdge(t: FullGraph, g: FullGraph): [Edge, number] | undefined {
+  const incidentEdges = Array.from(g.edges())
+    .filter((e) => incidentEdge(t, e))
+    .filter(
+      (e) =>
+        !util.getNodeProps(g.node(e.source)!).fixedRank &&
+        !util.getNodeProps(g.node(e.target)!).fixedRank,
+    );
+  // Incident edges sorted by least slack.
+  const slackEdges = incidentEdges
+    .map((e) => [e, slack(g, e)] as [Edge, number])
+    .sort(([e1, s1], [e2, s2]) => s1 - s2);
+
+  return slackEdges[0];
+}
+
+/**
+ * Given a spanning tree `t`, move all its nodes in `g` up `delta` ranks.
+ */
+function shiftRanks(t: FullGraph, g: FullGraph, delta: number) {
+  for (const id of t.nodes) {
+    const props = util.getNodeProps(g.node(id)!);
+    setRank(props, props.rank + delta);
+  }
+}
+
+/**
+ * The slack of an edge is the difference in its length (in ranks spanned) minus
+ * is minLength. A tight edge has slack = 0.
+ */
+function slack(g: FullGraph, e: Edge) {
+  const sourceRank = util.getNodeProps(g.node(e.source)!).rank;
+  const targetRank = util.getNodeProps(g.node(e.target)!).rank;
+  const minLength = util.getEdgeProps(g.edge(e)!).minLength;
+  return targetRank - sourceRank - minLength;
+}
+
+/**
+ * Find any edge with a negative cut value.
+ */
+function leaveEdge(g: FullGraph): Edge | undefined {
+  for (const edge of g.edges()) {
+    const value = g.edge(edge)!;
+    const layout = util.getEdgeProps(value);
+    if (layout.cutValue < 0) return edge;
+  }
+  return undefined;
+}
+
+/**
+ * Given an edge with a negative cut value, find the edge within the bounds that
+ * has the smallest slack.
+ */
+function enterEdge(t: FullGraph, g: FullGraph, edge: Edge): Edge | undefined {
+  let { source, target } = edge;
+  if (!g.hasEdge({ source, target })) {
+    [source, target] = [target, source];
+  }
+
+  const sourceNode = assertExists(t.node(source));
+  const targetNode = assertExists(t.node(target));
+  let tail = sourceNode;
+  let flip = false;
+
+  if (util.getNodeProps(sourceNode).lim > util.getNodeProps(targetNode).lim) {
+    tail = targetNode;
+    flip = true;
+  }
+
+  const candidates = Array.from(g.edges()).filter((edge) => {
+    const source = t.node(edge.source);
+    const target = t.node(edge.target);
+    // Nodes with a fixed rank are not eligible to swap.
+    if (
+      !source ||
+      util.getNodeProps(source).fixedRank ||
+      !target ||
+      util.getNodeProps(target).fixedRank
+    ) {
+      return false;
+    }
+    const sourceInBounds = isDescendant(source, tail, flip);
+    const targetInBounds = isDescendant(target, tail, !flip);
+    return sourceInBounds && targetInBounds;
+  });
+
+  const candidate = candidates
+    .map<[Edge, number]>((edge) => [edge, slack(g, edge)])
+    .sort((a, b) => a[1] - b[1])
+    .map(([edge]) => edge)[0];
+
+  return candidate;
+}
+
+/**
+ * `source` is a descendant of `root` if its min and max ranks are completely
+ * bounded by `root`.
+ */
+function isDescendant(source: Node, root: Node, flip: boolean): boolean {
+  const sourceLayout = util.getNodeProps(source);
+  const rootLayout = util.getNodeProps(root);
+  const lowerBound = rootLayout.low <= sourceLayout.lim;
+  const upperBound = sourceLayout.lim <= rootLayout.lim;
+  const inBounds = lowerBound && upperBound;
+  return flip === inBounds;
+}
+
+/**
+ * Given a spanning tree, initialize lim and low for each node.
+ */
+function initLowLimValues(t: FullGraph, root = Array.from(t.children())[0]): void {
+  dfsAssignLowLim(t, new Set(), 1, root);
+
+  function dfsAssignLowLim(
+    tree: FullGraph,
+    visited: Set<NodeId>,
+    nextLim: number,
+    id: NodeId,
+    parent?: NodeId,
+  ): number {
+    const low = nextLim;
+    tree.setParent(id, parent);
+
+    visited.add(id);
+    for (const n of tree.neighbors(id)) {
+      if (!visited.has(n)) {
+        nextLim = dfsAssignLowLim(tree, visited, nextLim, n, id);
+      }
+    }
+
+    const layout = util.getNodeProps(tree.node(id)!);
+    layout.low = low;
+    layout.lim = nextLim++;
+
+    return nextLim;
+  }
+}
+
+/**
+ * Given two edges in a spanning tree, swap them and reset graph layout values.
+ */
+function exchangeEdges(t: FullGraph, g: FullGraph, a: Edge, b: Edge): void {
+  const { source: sa, target: ta } = a;
+  t.removeEdge({ source: sa, target: ta });
+  t.removeEdge({ source: ta, target: sa });
+  const { source: sb, target: tb } = b;
+  const st = { source: sb, target: tb };
+  const ts = { source: tb, target: sb };
+  t.setEdge(st, st);
+  t.setEdge(ts, ts);
+
+  initLowLimValues(t);
+  initCutValues(t, g);
+  updateRanks(t, g);
+}
+
+function updateRanks(t: FullGraph, g: FullGraph) {
+  const root = Array.from(t.children());
+  const ids = dfs(t, root);
+  for (const id of ids) {
+    const props = util.getNodeProps(g.node(id)!);
+    if (props.fixedRank) continue;
+    const parent = t.parent(id);
+    if (!g.hasNode(parent)) continue;
+    let edge = g.edge({ source: id, target: parent });
+    let flipped = false;
+    if (!edge) {
+      edge = g.edge({ source: parent, target: id });
+      flipped = true;
+    }
+
+    const minLength = util.getEdgeProps(edge!).minLength;
+    const rank = util.getNodeProps(g.node(parent)!).rank + (flipped ? minLength : -minLength);
+    setRank(props, rank);
+  }
+}
+
+/**
+ * Given a spanning tree and a graph, determine the cut value for a node.
+ */
+function calcCutValue(t: FullGraph, g: FullGraph, child: NodeId): number {
+  assert(t.hasNode(child), "Child not in tree");
+  const parent = t.parent(child);
+  assert(t.hasNode(parent), "Root has no cut value");
+  let childIsTail = true;
+
+  let graphEdge: Edge = { source: child, target: parent };
+  if (!g.hasEdge(graphEdge)) {
+    childIsTail = false;
+    graphEdge = { source: parent, target: child };
+  }
+
+  let cutValue = util.getEdgeProps(graphEdge!).weight;
+
+  for (const edge of g.edges(child)) {
+    const isOutEdge = edge.source === child;
+    const other: NodeId = isOutEdge ? edge.target : edge.source;
+
+    if (other !== parent) {
+      const pointsToHead = isOutEdge === childIsTail;
+      const otherWeight = util.getEdgeProps(edge).weight;
+
+      cutValue += pointsToHead ? otherWeight : -otherWeight;
+
+      const otherEdge: Edge = { source: child, target: other };
+      if (t.hasEdge(otherEdge)) {
+        const otherCutValue = util.getEdgeProps(t.edge(otherEdge)!).cutValue;
+        cutValue += pointsToHead ? -otherCutValue : otherCutValue;
+      }
+    }
+  }
+
+  return cutValue;
+}
+
+/**
+ * Assign initial cut values to a spanning tree edges. Cut value on an edge is
+ * the sum of all weights to the source node, minus the sum of all weights to
+ * the target node.
+ */
+function initCutValues(t: FullGraph, g: FullGraph): void {
+  // Proceed from leaves in, for efficient iterative cut value. See [gansner].
+  const nodes = dfs(t, t.children(), Order.POST);
+  for (const id of nodes) {
+    assignCutValue(t, g, id);
+  }
+}
+
+function assignCutValue(t: FullGraph, g: FullGraph, id: NodeId) {
+  const parent = t.parent(id);
+  if (!t.hasNode(parent)) return;
+  const cutValue = calcCutValue(t, g, id);
+  let edge = t.edge({ source: id, target: parent });
+  if (edge) util.getEdgeProps(edge).cutValue = cutValue;
+  edge = t.edge({ target: id, source: parent });
+  if (edge) util.getEdgeProps(edge).cutValue = cutValue;
+}
+
+/**
+ * Nesting takes an arbitrary graph and ensures all subgraphs are connected, by
+ * introducing virtual "border" nodes between distinct subgraphs (those
+ * subgraphs having no connections).
+ */
+export const nesting = {
+  run(g: FullGraph): void {
+    const root = util.addVirtualNode(g, util.Virtual.ROOT, {}, undefined, "_root_");
+    const depths = treeDepths(g);
+    const height = Math.max(...Object.values(depths)) - 1;
+    const nodeSep = 2 * height + 1;
+    const weight = sumWeights(g);
+
+    util.getGraphProps(g).nestingRoot = root;
+    util.getGraphProps(g).nodeRankFactor = nodeSep;
+
+    for (const edge of g.edges()) {
+      util.getEdgeProps(g.edge(edge)!).minLength *= nodeSep;
+    }
+
+    for (const child of g.children()) {
+      nestingDfs(child);
+    }
+
+    function treeDepths(g: FullGraph): Record<NodeId, number> {
+      const depths: Record<NodeId, number> = {};
+      function dfs(id: NodeId, depth: number) {
+        depths[id] = depth;
+        const children = g.children(id);
+        for (const child of children) {
+          dfs(child, depth + 1);
+        }
+      }
+      for (const child of g.children()) {
+        dfs(child, 1);
+      }
+      return depths;
+    }
+
+    function sumWeights(g: FullGraph): number {
+      return Array.from(g.edges())
+        .map((e) => util.getEdgeProps(g.edge(e)!))
+        .reduce((acc, el) => acc + el.weight, 0);
+    }
+
+    function nestingDfs(id: NodeId) {
+      const children = g.children(id);
+      if (children.size === 0) {
+        if (id !== root) {
+          const rootId = util.makeEdge(root, id, {
+            weight: 0,
+            minLength: nodeSep,
+          });
+          g.setEdge(rootId, rootId);
+        }
+        return;
+      }
+
+      const top = util.addBorderNode(g, util.Border.TOP);
+      const bottom = util.addBorderNode(g, util.Border.BOTTOM);
+      const layout = util.getNodeProps(g.node(id)!);
+
+      g.setParent(top, id);
+      g.setParent(bottom, id);
+      layout.top = top;
+      layout.bottom = bottom;
+
+      for (const child of children) {
+        nestingDfs(child);
+
+        const childLayout = util.getNodeProps(g.node(child)!);
+        const childTop = childLayout.top || child;
+        const childBottom = childLayout.bottom || child;
+        const thisWeight = (childLayout.top ? 1 : 2) * weight;
+        const minLength = childTop !== childBottom ? 1 : height - depths[id] + 1;
+
+        const tct = util.makeEdge(top, childTop, {
+          weight: thisWeight,
+          minLength,
+          nestingEdge: true,
+        });
+        const cbb = util.makeEdge(childBottom, bottom, {
+          weight: thisWeight,
+          minLength,
+          nestingEdge: true,
+        });
+        if (top !== childTop) g.setEdge(tct, tct);
+        if (childBottom !== bottom) g.setEdge(cbb, cbb);
+      }
+
+      if (!g.hasNode(g.parent(id))) {
+        const rootTop = util.makeEdge(root, top, {
+          weight: 0,
+          minLength: height + depths[id],
+        });
+        g.setEdge(rootTop, rootTop);
+      }
+    }
+  },
+
+  undo(g: FullGraph): void {
+    const layout = util.getGraphProps(g);
+    if (layout.nestingRoot) g.removeNode(layout.nestingRoot);
+    layout.nestingRoot = undefined;
+    for (const e of g.edges()) {
+      const { nestingEdge } = util.getEdgeProps(g.edge(e)!);
+      if (nestingEdge) {
+        g.removeEdge(e);
+      }
+    }
+  },
+};
+
+/* Function to safely set the rank of a node. If the node is fixed rank, does
+ * nothing. Otherwise, sets the rank to this value. */
+function setRank(props: NodeProperties, rank: number): void {
+  assertFinite(rank, `Non-finite rank ${rank}`);
+  if (!props.fixedRank) {
+    props.rank = rank;
+  }
+}
+
+export const TEST_ONLY = {
+  calcCutValue,
+  enterEdge,
+  exchangeEdges,
+  feasibleTree,
+  initCutValues,
+  initLowLimValues,
+  leaveEdge,
+  longestPath,
+  nesting,
+  networkSimplex,
+  normalizeRanks,
+  removeEmptyRanks,
+  simplify,
+};

package/src/layout/hierarchic.ts

@@ -0,0 +1,2 @@
+export { layout } from "./hierarchic/layout.ts";
+export { HierarchicalLayoutManager } from "./hierarchic/manager.ts";