@davidsouther/agathon 0.0.0-stage → 2026.11.1

package/src/layout/hierarchic/order.ts

@@ -0,0 +1,321 @@
+import type { Edge, FullGraph, NodeId } from "../../types.ts";
+import * as util from "../util.ts";
+import { initOrder } from "../util.ts";
+
+import * as debug from "./debug.ts";
+
+/**
+ * Given a graph with `rank` computed, determine an ideal ordering for nodes
+ * within each rank, heuristically minimizing edge crosses. While NP-complete,
+ * there are a number of heuristic approaches which all boil down to
+ * polynomial bounded "best attempt" solutions.
+ *
+ * The general solution is reducible to the problem of minimizing crossings
+ * for two input layers with arbitrary edges between the layers, and then
+ * "sweeping" that pass up and down the rank layers, stopping at either N (=4)
+ * improvements or when no improvement is found. Within each sweep, one layer
+ * (bottom for sweeping down or top for sweeping up) is permuted, following a
+ * similar polynomial cutoff.
+ *
+ * See [Forster], [Junger], and [Barth] papers linked in docs/tsabre for details
+ * & proofs of correctness & efficiency.
+ */
+export function order(g: FullGraph): void {
+  const { printDebug } = util.getGraphProps(g);
+
+  // initOrder returns a 2-d array of NodeIds, where row is the rank of the
+  // node, and the node will be put in the column which is its ordering.
+  const layering = initOrder(g);
+
+  // Assign the initial layering into the graph, so that there's something to
+  // start with.
+  assignOrder(g, layering);
+
+  if (printDebug) {
+    debug.printLayering(layering, g);
+  }
+
+  let bestCC = Number.POSITIVE_INFINITY;
+  let best = layering.map((r) => r.slice(0)); // Copy the layering
+
+  // i tracks the iteration step, while lastBest tracks the number of
+  // iterations since a better ordering was found.
+  for (
+    let i = 0, lastBest = 0;
+    // If bestCC is 0 crossings, end early.
+    bestCC > 0 &&
+    // If after four sweeps there hasn't been an improvement, call it good.
+    lastBest < 4 &&
+    // End at 24 iterations, max.
+    i < 24;
+    ++i, ++lastBest
+  ) {
+    reorder(g, i, layering);
+
+    const cc = crossCount(g, layering);
+    if (cc < bestCC) {
+      // Counted fewer crossings, so reset the lastBest count and record
+      // the new best crossing.
+      lastBest = 0;
+      best = layering.map((r) => r.slice(0)); // Copy the layering
+      bestCC = cc;
+    }
+  }
+
+  // Copy the best ordering into the graph.
+  assignOrder(g, best);
+}
+
+function reorder(g: FullGraph, i: number, layering: NodeId[][]) {
+  // sweepLayerGraphs will assign an ordering to each node. When sweeping,
+  // go down bias left, up bias left, down bias right, up bias right, and
+  // repeat.
+  const topToBottom = i % 2 === 0;
+  const biasRight = i % 4 >= 2;
+  if (topToBottom) {
+    sweepLayerGraphsDown(g, layering, biasRight);
+  } else {
+    sweepLayerGraphsUp(g, layering, biasRight);
+  }
+}
+
+/**
+ * Given a computed layers matrix, assign those indices back into the node's
+ * `order` property.
+ */
+function assignOrder(g: FullGraph, layers: NodeId[][]): void {
+  for (let layer of layers) {
+    layer = layer || []; // some situations which can result in empty ranks
+    for (let i = 0; i < layer.length; i++) {
+      if (layer[i] && g.hasNode(layer[i])) {
+        util.getNodeProps(g.node(layer[i])!).order = i;
+      }
+    }
+  }
+}
+
+/**
+ * Given a list of "layer" graphs, that is, having only nodes on adjacent ranks
+ * with edges between them, "sweep" through the list reordering nodes to reduce
+ * crossings.
+ */
+function sweepLayerGraphsDown(g: FullGraph, layering: NodeId[][], biasRight: boolean): void {
+  for (let i = 0; i < layering.length - 1; i++) {
+    sortLayer(
+      g,
+      layering,
+      i + 1,
+      (id: NodeId) => g.inEdges(id),
+      ({ source }) => source,
+      biasRight,
+    );
+  }
+}
+
+function sweepLayerGraphsUp(g: FullGraph, layering: NodeId[][], biasRight: boolean): void {
+  for (let i = layering.length - 1; i > 0; i--) {
+    sortLayer(
+      g,
+      layering,
+      i - 1,
+      (id: NodeId) => g.outEdges(id),
+      ({ target }) => target,
+      biasRight,
+    );
+  }
+}
+
+function updateOrdering(g: FullGraph, sources: NodeId[]): void {
+  for (let i = 0; i < sources.length; i++) {
+    const id = sources[i];
+    util.getNodeProps(g.node(id)!).order = i;
+  }
+}
+
+/**
+ * Given a graph and a layering, count the number of crossing edges.
+ *
+ * Uses an O(E log V) algorithm from Barth et al that builds an accumulator tree
+ * to count crossings as they are inserted & discoverd.
+ */
+function crossCount(g: FullGraph, layering: NodeId[][]): number {
+  let cc = 0;
+  for (let i = 1; i < layering.length; i++) {
+    cc += twoLayerCrossCounting(layering[i - 1], layering[i]);
+  }
+  return cc;
+
+  function twoLayerCrossCounting(top: NodeId[], bottom: NodeId[]): number {
+    const bottomEntries = sortLayers(g, top, bottom);
+
+    // Prepare accumulator tree, a binary tree large enough to build a
+    // complete tree containing all nodes in `bottom`.
+    let firstIndex = 1;
+    while (firstIndex < bottom.length) firstIndex <<= 1;
+    const treeSize = 2 * firstIndex - 1;
+    firstIndex -= 1;
+    const tree = new Array(treeSize).fill(0);
+
+    // Count crossings with weight, eg if a weight 1 and weight 2 edge cross,
+    // the total cross counting is weight 3. This implies crossings are
+    // preferred on lower weight edges.
+    let cc = 0;
+    for (const { pos, weight } of bottomEntries) {
+      let index = pos + firstIndex;
+      tree[index] += weight;
+      let weightSum = 0;
+      while (index > 0) {
+        if (index % 2) {
+          weightSum += tree[index + 1];
+        }
+        index = (index - 1) >> 1;
+        tree[index] += weight;
+      }
+      cc += weight * weightSum;
+    }
+    return cc;
+  }
+
+  // Return a list including the position and weight of all edges, sorted by
+  // the edge's location in the top layer, then by its position in the bottom
+  // layer.
+  function sortLayers(
+    g: FullGraph,
+    top: NodeId[],
+    bottom: NodeId[],
+  ): Array<{ pos: number; weight: number }> {
+    // Map the lower layer's IDs to their position in the list.
+    const bottomPositions = bottom.reduce(
+      (a, id, i) => {
+        a[id] = i;
+        return a;
+      },
+      {} as Record<NodeId, number>,
+    );
+    return top
+      .map((id) =>
+        Array.from(g.outEdges(id))
+          .map(getBottomEdge)
+          .sort((a, b) => a.pos - b.pos),
+      )
+      .reduce((a, i) => a.concat(i), []);
+
+    function getBottomEdge(e: Edge): { pos: number; weight: number } {
+      return {
+        pos: bottomPositions[e.target],
+        weight: util.getEdgeProps(g.edge(e)!).weight,
+      };
+    }
+  }
+}
+
+/**
+ * A barycenter encodes a 1-d coordinate & weighting against it.
+ */
+export interface Barycenter {
+  id: NodeId;
+  barycenter?: number;
+  weight?: number;
+}
+
+/**
+ * Given a set of nodes in a graph, find the horizontal center for each node.
+ * The horizontal center is the point that keeps it equally placed between all
+ * incoming node edges, obeying weightedness of edges. From [Forster],
+ * is defined as the arithmetic mean of the relative positions of its
+ * neighbors b(v) = 1 / |N(v)|  ∑v∈N(v) pos(v)
+ */
+function barycenter(
+  g: FullGraph,
+  nodes: NodeId[],
+  edgeFn: (n: NodeId) => Iterable<Edge>,
+  neighborFn: (edge: Edge) => NodeId,
+): Barycenter[] {
+  function findCenter(id: NodeId): Barycenter {
+    const neighbors = new Set(edgeFn(id));
+    if (neighbors.size === 0) return { id };
+    let sum = 0;
+    let weight = 0;
+    for (const e of neighbors) {
+      const nid = neighborFn(e);
+      const order = util.getNodeProps(g.node(nid)!).order;
+      const edgeWeight = util.getEdgeProps(g.edge(e)!).weight;
+      sum += edgeWeight * order;
+      weight += edgeWeight;
+    }
+    return {
+      id,
+      barycenter: sum / weight,
+      weight,
+    };
+  }
+
+  return nodes.filter((id) => g.hasNode(id)).map(findCenter);
+}
+
+/**
+ * Given a graph and layering, sort one layer based on barycenters (with
+ * neighbors selected via edgeFn |> neighborFn). Updates layering and the graph
+ * in place.
+ */
+function sortLayer(
+  g: FullGraph,
+  layering: NodeId[][],
+  sweep: number,
+  edgeFn: (n: NodeId) => Iterable<Edge>,
+  neighborFn: (edge: Edge) => NodeId,
+  biasRight: boolean,
+): void {
+  const centers = barycenter(g, layering[sweep], edgeFn, neighborFn);
+  centers.sort(barycenterComparator(layering[sweep], biasRight));
+  layering[sweep] = centers.map(({ id }) => id);
+  // update ordering in g for next sweep pass
+  updateOrdering(g, layering[sweep]);
+}
+
+/**
+ * Returns a comparator function which sorts two Barycenters. If the centers are
+ * equal, bias determines which order to place the nodes in. This is a complete
+ * ordering, no two nodes will have a stable sort value.
+ */
+function barycenterComparator(
+  original: NodeId[],
+  bias: boolean,
+): (a: Barycenter, b: Barycenter) => number {
+  return (a: Barycenter, b: Barycenter) => {
+    if (a === b) return 0; // Allow stable sort
+
+    const baryA = a.barycenter || 0;
+    const baryB = b.barycenter || 0;
+
+    // Normalize to just the sign bit.
+    const sort = Math.sign(baryA - baryB);
+    if (sort !== 0) return sort;
+
+    // This is necessary for consistent ordering, because the order of arguments
+    // to the compare function is implementation dependant. In practice, that
+    // means chrome and firefox end up with the same overall results, but with
+    // each row reversed from the other.
+    //
+    // This probably makes the entire algorithm O(N log(N^2)). Or maybe
+    // O(N^2 log(N)). I'm not really sure how to handle a log(N) operation which
+    // itself uses N time.
+    const baryAIdx = original.indexOf(a.id);
+    const baryBIdx = original.indexOf(b.id);
+    if (bias) {
+      return baryBIdx - baryAIdx;
+    } else {
+      return baryAIdx - baryBIdx;
+    }
+  };
+}
+
+/** Functions for tests. */
+export const TEST_ONLY = {
+  assignOrder,
+  crossCount,
+  barycenter,
+  sortLayer,
+  barycenterComparator,
+  initOrder,
+};