@knowvah/dot-engine 0.1.0

package/src/layout/fdp/ports.ts

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Cluster expansion ports: after the parent layout positions a
+ * cluster's derived node, the angles of its edges induce boundary
+ * ports for the cluster's own recursive layout.
+ *
+ * Spec read at the 15.0.0 tag.
+ *
+ * @see lib/fdpgen/layout.c:getEdgeList / genPorts / expandCluster
+ *      (15.0.0)
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Node } from '../../model/node.js';
+import type { Edge } from '../../model/edge.js';
+import {
+  type Bport,
+  gdata,
+  dndata,
+  getDnode,
+  realEdges,
+} from './fdp-model.js';
+
+/** Maximum angular change: 2 degrees. @see lib/fdpgen/layout.c:ANG */
+const ANG = Math.PI / 90;
+
+/** Edge record for angular sorting. @see lib/fdpgen/layout.c:erec */
+interface Erec {
+  e: Edge;
+  alpha: number;
+  dist2: number;
+}
+
+/** Sort edges by angle, then distance. @see lib/fdpgen/layout.c:ecmp */
+function ecmp(e1: Erec, e2: Erec): number {
+  if (e1.alpha > e2.alpha) return 1;
+  if (e1.alpha < e2.alpha) return -1;
+  if (e1.dist2 > e2.dist2) return 1;
+  if (e1.dist2 < e2.dist2) return -1;
+  return 0;
+}
+
+/** Spread runs of equal angles by up to ANG. @see layout.c:576-601 */
+function spreadEqualAngles(erecs: Erec[], deg: number): void {
+  let i = 0;
+  while (i < deg - 1) {
+    const a = erecs[i]!.alpha;
+    let j = i + 1;
+    while (j < deg && erecs[j]!.alpha === a) j++;
+    if (j === i + 1) {
+      i = j;
+    } else {
+      const bnd = j === deg ? Math.PI : erecs[j]!.alpha;
+      const delta = Math.min((bnd - a) / (j - i), ANG);
+      let inc = 0;
+      for (; i < j; i++) {
+        erecs[i]!.alpha += inc;
+        inc += delta;
+      }
+    }
+  }
+}
+
+/**
+ * Counterclockwise-sorted list of the derived edges at n, with ties
+ * broken apart angularly. Assumes g has an initial layout.
+ * @see lib/fdpgen/layout.c:getEdgeList
+ */
+export function getEdgeList(n: Node, g: Graph): Erec[] {
+  const deg = dndata(n).deg;
+  const erecs: Erec[] = [];
+  // agfstedge order: out-edges then in-edges
+  for (const e of [...n.outEdges(g), ...n.inEdges(g)]) {
+    const m = e.head === n ? e.tail : e.head;
+    const dx = m.info.pos![0]! - n.info.pos![0]!;
+    const dy = m.info.pos![1]! - n.info.pos![1]!;
+    erecs.push({ e, alpha: Math.atan2(dy, dx), dist2: dx * dx + dy * dy });
+  }
+  if (erecs.length !== deg) {
+    throw new Error(`fdp getEdgeList: ${erecs.length} edges vs deg ${deg}`);
+  }
+  erecs.sort(ecmp);
+
+  /* ensure no two angles are equal */
+  if (deg >= 2) spreadEqualAngles(erecs, deg);
+
+  return erecs;
+}
+
+/**
+ * Append the ports corresponding to one derived edge at n to pp,
+ * fanning multi-edges between alpha and bnd. Real-edge order reverses
+ * when n is the later-created endpoint (C pointer comparison).
+ * @see lib/fdpgen/layout.c:genPorts
+ */
+export function genPorts(
+  n: Node, er: Erec, pp: Bport[], idx: number, bnd: number,
+): number {
+  const e = er.e;
+  const cnt = e.info.count ?? 0;
+  const other = e.head === n ? e.tail : e.head;
+
+  const delta = Math.min((bnd - er.alpha) / cnt, ANG);
+  // C: n < other (pointer order) → ascending fill; else reversed
+  const fwd = n.id < other.id;
+  const fan = fwd
+    ? { i: idx, inc: 1, angle: er.alpha, delta }
+    : { i: idx + cnt - 1, inc: -1, angle: er.alpha + delta * (cnt - 1), delta: -delta };
+
+  fillPorts(n, e, pp, fan);
+  return idx + cnt;
+}
+
+/** Write one derived edge's real-edge ports at fanned angles. */
+function fillPorts(
+  n: Node,
+  e: Edge,
+  pp: Bport[],
+  fan: { i: number; inc: number; angle: number; delta: number },
+): void {
+  for (const el of realEdges(e)) {
+    pp[fan.i] = {
+      e: el,
+      n: getDnode(el.tail) === n ? el.tail : el.head,
+      alpha: fan.angle,
+    };
+    fan.i += fan.inc;
+    fan.angle += fan.delta;
+  }
+}
+
+/**
+ * Attach ports induced by the layout of cg to the cluster subgraph
+ * that derived node n represents.
+ * @see lib/fdpgen/layout.c:expandCluster
+ */
+export function expandCluster(n: Node, cg: Graph): Graph {
+  const sg = dndata(n).clust!;
+  const sz = dndata(n).wdeg;
+  if (sz !== 0) {
+    const pp: Bport[] = [];
+    /* create sorted list of edges of n */
+    const es = getEdgeList(n, cg);
+
+    /* generate ports from edges */
+    let idx = 0;
+    for (let k = 0; k < es.length; k++) {
+      const next = es[k + 1];
+      const bnd = next !== undefined ? next.alpha : 2 * Math.PI + es[0]!.alpha;
+      idx = genPorts(n, es[k]!, pp, idx, bnd);
+    }
+    if (idx !== sz) {
+      throw new Error(`fdp expandCluster: ${idx} ports vs wdeg ${sz}`);
+    }
+
+    gdata(sg).ports = pp;
+    gdata(sg).nports = sz;
+  }
+  return sg;
+}

package/src/layout/fdp/tlayout-init.ts

@@ -0,0 +1,230 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * fdp initial placement: seed the RNG, size the boundary ellipse/box,
+ * place ports on the ellipse and free nodes within it.
+ *
+ * drand48 call order is load-bearing (exact LCG port in
+ * src/common/random.ts); node iteration is the component's id order
+ * and the per-node edge scan is out-edges then in-edges (agfstedge).
+ *
+ * Spec read at the 15.0.0 tag.
+ *
+ * @see lib/fdpgen/tlayout.c:initPositions (15.0.0)
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Node } from '../../model/node.js';
+import type { Edge } from '../../model/edge.js';
+import type { Point } from '../../model/geom.js';
+import { srand48, drand48 } from '../../common/random.js';
+import {
+  type Bport,
+  dndata,
+  isPort,
+  hasPos,
+  gdata,
+  P_SET,
+} from './fdp-model.js';
+import { parms, EXPFACTOR, INIT_RANDOM } from './tlayout-parms.js';
+
+/** Pinned-node bounding box, C-style running min/max. */
+interface PinBB {
+  llx: number;
+  lly: number;
+  urx: number;
+  ury: number;
+}
+
+/** All edges of np in g: out-edges then in-edges (agfstedge order). */
+function allEdges(g: Graph, np: Node): Edge[] {
+  return [...np.outEdges(g), ...np.inEdges(g)];
+}
+
+/**
+ * Average the positions of already-placed neighbors; fall back to a
+ * random point in the boundary ellipse.
+ * @see lib/fdpgen/tlayout.c:initPositions (port branch, unpinned case)
+ */
+function placeByNeighbors(g: Graph, np: Node, ctr: Point): void {
+  const p: Point = { x: 0.0, y: 0.0 };
+  const cnt = averagePlacedNeighbors(g, np, p);
+  if (cnt > 1) {
+    np.info.pos![0] = p.x;
+    np.info.pos![1] = p.y;
+  } else if (cnt === 1) {
+    np.info.pos![0] = 0.98 * p.x + 0.1 * ctr.x;
+    np.info.pos![1] = 0.9 * p.y + 0.1 * ctr.y;
+  } else {
+    const angle = Math.PI * 2.0 * drand48();
+    const radius = 0.9 * drand48();
+    np.info.pos![0] = radius * parms.Wd * Math.cos(angle);
+    np.info.pos![1] = radius * parms.Ht * Math.sin(angle);
+  }
+  dndata(np).pinned = P_SET;
+}
+
+/**
+ * Running average of already-placed neighbor positions into p;
+ * returns the neighbor count.
+ * @see lib/fdpgen/tlayout.c:initPositions (cnt accumulation loop)
+ */
+function averagePlacedNeighbors(g: Graph, np: Node, p: Point): number {
+  let cnt = 0;
+  for (const ep of allEdges(g, np)) {
+    if (ep.head === ep.tail) continue;
+    const op = ep.head === np ? ep.tail : ep.head;
+    if (!hasPos(op)) continue;
+    if (cnt) {
+      p.x = (p.x * cnt + op.info.pos![0]!) / (cnt + 1);
+      p.y = (p.y * cnt + op.info.pos![1]!) / (cnt + 1);
+    } else {
+      p.x = op.info.pos![0]!;
+      p.y = op.info.pos![1]!;
+    }
+    cnt++;
+  }
+  return cnt;
+}
+
+/** Bounding box and count of pinned nodes. */
+function pinnedBB(g: Graph): { bb: PinBB; nPos: number } {
+  const bb: PinBB = { llx: 0, lly: 0, urx: 0, ury: 0 };
+  let nPos = 0;
+  for (const np of g.nodes.values()) {
+    if (dndata(np).pinned) {
+      if (nPos) {
+        bb.llx = Math.min(np.info.pos![0]!, bb.llx);
+        bb.lly = Math.min(np.info.pos![1]!, bb.lly);
+        bb.urx = Math.max(np.info.pos![0]!, bb.urx);
+        bb.ury = Math.max(np.info.pos![1]!, bb.ury);
+      } else {
+        bb.urx = bb.llx = np.info.pos![0]!;
+        bb.ury = bb.lly = np.info.pos![1]!;
+      }
+      nPos++;
+    }
+  }
+  return { bb, nPos };
+}
+
+/**
+ * Boundary sizing for the n_pos > 1 case: grow Wd/Ht to cover the
+ * pinned bbox, then construct the enclosing ellipse.
+ * @see lib/fdpgen/tlayout.c:initPositions (n_pos > 1 branch)
+ */
+function boundaryFromBB(bb: PinBB): Point {
+  const ctr: Point = {
+    x: (bb.llx + bb.urx) / 2.0,
+    y: (bb.lly + bb.ury) / 2.0,
+  };
+  const width = EXPFACTOR * (bb.urx - bb.llx);
+  const height = EXPFACTOR * (bb.ury - bb.lly);
+  sizeBoundary(width, height);
+
+  /* Construct enclosing ellipse */
+  const alpha = Math.atan2(parms.Ht, parms.Wd);
+  parms.Wd = parms.Wd / Math.cos(alpha);
+  parms.Ht = parms.Ht / Math.sin(alpha);
+  return ctr;
+}
+
+/**
+ * Grow Wd/Ht so the boundary has at least the default area while
+ * matching the pinned bbox aspect.
+ * @see lib/fdpgen/tlayout.c:initPositions (quot branches)
+ */
+function sizeBoundary(width: number, height: number): void {
+  const area = 4.0 * parms.Wd * parms.Ht;
+  let quot = width * height / area;
+  if (quot >= 1.0) { /* If bbox has large enough area, use it */
+    parms.Wd = width / 2.0;
+    parms.Ht = height / 2.0;
+  } else if (quot > 0.0) { /* else scale up to have enough area */
+    quot = 2.0 * Math.sqrt(quot);
+    parms.Wd = width / quot;
+    parms.Ht = height / quot;
+  } else if (width > 0) { /* height is 0 */
+    parms.Wd = width / 2.0;
+    parms.Ht = area / width / 2.0;
+  } else if (height > 0) { /* width is 0 */
+    parms.Wd = area / height / 2.0;
+    parms.Ht = height / 2.0;
+  }
+  /* If width = height = 0, keep Wd/Ht as for the n_pos == 0 case */
+}
+
+/**
+ * Port-graph placement: ports pinned on the ellipse, other nodes by
+ * neighbor averaging or randomly inside it.
+ * @see lib/fdpgen/tlayout.c:initPositions (pp branch)
+ */
+function placeWithPorts(g: Graph, pp: Bport[], ctr: Point): void {
+  for (const port of pp) { /* position ports on ellipse */
+    const np = port.n;
+    np.info.pos![0] = parms.Wd * Math.cos(port.alpha) + ctr.x;
+    np.info.pos![1] = parms.Ht * Math.sin(port.alpha) + ctr.y;
+    dndata(np).pinned = P_SET;
+  }
+  for (const np of g.nodes.values()) {
+    if (isPort(np)) continue;
+    if (dndata(np).pinned) {
+      np.info.pos![0]! -= ctr.x;
+      np.info.pos![1]! -= ctr.y;
+    } else {
+      placeByNeighbors(g, np, ctr);
+    }
+  }
+}
+
+/** Random/translated placement when there are no ports. */
+function placeWithoutPorts(g: Graph, nPos: number, ctr: Point): void {
+  if (nPos) { /* If positioned nodes */
+    for (const np of g.nodes.values()) {
+      if (dndata(np).pinned) {
+        np.info.pos![0]! -= ctr.x;
+        np.info.pos![1]! -= ctr.y;
+      } else {
+        np.info.pos![0] = parms.Wd * (2.0 * drand48() - 1.0);
+        np.info.pos![1] = parms.Ht * (2.0 * drand48() - 1.0);
+      }
+    }
+  } else { /* No ports or positions; place randomly */
+    for (const np of g.nodes.values()) {
+      np.info.pos![0] = parms.Wd * (2.0 * drand48() - 1.0);
+      np.info.pos![1] = parms.Ht * (2.0 * drand48() - 1.0);
+    }
+  }
+}
+
+/**
+ * Create the initial layout of one derived component.
+ * @see lib/fdpgen/tlayout.c:initPositions
+ */
+export function initPositions(g: Graph, pp: Bport[] | null): Point {
+  const nG = g.nodes.size - gdata(g).nports;
+  const { bb, nPos } = pinnedBB(g);
+  let ctr: Point = { x: 0, y: 0 };
+
+  const size = parms.K * (Math.sqrt(nG) + 1.0);
+  parms.Wd = parms.Ht = EXPFACTOR * (size / 2.0);
+  if (nPos === 1) {
+    ctr = { x: bb.llx, y: bb.lly };
+  } else if (nPos > 1) {
+    ctr = boundaryFromBB(bb);
+  }
+
+  /* Set seed value */
+  const localSeed = parms.smode === INIT_RANDOM
+    ? parms.seed
+    : Math.floor(Date.now() / 1000); // C: time(NULL)
+  srand48(localSeed);
+
+  if (pp) {
+    placeWithPorts(g, pp, ctr);
+  } else {
+    placeWithoutPorts(g, nPos, ctr);
+  }
+
+  return ctr;
+}

package/src/layout/fdp/tlayout-parms.ts

@@ -0,0 +1,234 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * fdp layout parameters: the fdp_parms process defaults, the static
+ * parms_t working set, the cooling schedule, and parameter resolution
+ * from graph attributes.
+ *
+ * Spec read at the 15.0.0 tag.
+ *
+ * @see lib/fdpgen/tlayout.c (15.0.0) — parms_t, fdp_initParams,
+ *      init_params, cool, reset_params
+ * @see lib/common/globals.c (15.0.0) — fdpParms defaults
+ */
+
+import type { Graph } from '../../model/graph.js';
+import { lateDouble, lateInt } from '../../common/nodeinit.js';
+import { type XParams, aggetGraph } from './fdp-model.js';
+
+// ---------------------------------------------------------------------------
+// Constants — @see lib/fdpgen/tlayout.c:96-101, lib/neatogen/neato.h:27-30
+// ---------------------------------------------------------------------------
+
+/** @see lib/fdpgen/tlayout.c:EXPFACTOR */
+export const EXPFACTOR = 1.2;
+/** @see lib/fdpgen/tlayout.c:DFLT_maxIters */
+const DFLT_MAX_ITERS = 600;
+/** @see lib/fdpgen/tlayout.c:DFLT_K */
+const DFLT_K = 0.3;
+/** @see lib/fdpgen/tlayout.c:DFLT_Cell */
+const DFLT_CELL = 0.0;
+/** @see lib/fdpgen/tlayout.c:DFLT_seed */
+const DFLT_SEED = 1;
+
+/** @see lib/neatogen/neato.h:INIT_SELF */
+export const INIT_SELF = 0;
+/** @see lib/neatogen/neato.h:INIT_REGULAR */
+export const INIT_REGULAR = 1;
+/** @see lib/neatogen/neato.h:INIT_RANDOM */
+export const INIT_RANDOM = 2;
+/** @see lib/fdpgen/tlayout.c:DFLT_smode */
+const DFLT_SMODE = INIT_RANDOM;
+
+// ---------------------------------------------------------------------------
+// fdp_parms defaults — @see lib/common/globals.c (15.0.0)
+// ---------------------------------------------------------------------------
+
+/**
+ * Process-level fdp defaults ("possibly set via command line; -1
+ * indicates unset"). The CLI flags (-L*) are not ported; the struct is
+ * kept because fdp_initParams and init_edge read it.
+ *
+ * @see lib/common/globals.c:fdpParms
+ * @see lib/fdpgen/fdp.h:fdpParms_t
+ */
+export const fdpParms = {
+  useGrid: 1,
+  useNew: 1,
+  numIters: -1,
+  unscaled: 50,
+  C: 0.0,
+  Tfact: 1.0,
+  K: -1.0,
+  T0: -1.0,
+};
+
+// ---------------------------------------------------------------------------
+// parms — actual parameters used (static parms_t in C)
+// ---------------------------------------------------------------------------
+
+/** @see lib/fdpgen/tlayout.c:parms_t */
+export interface TParms {
+  useGrid: number;
+  useNew: number;
+  seed: number;
+  numIters: number;
+  maxIters: number;
+  unscaled: number;
+  C: number;
+  Tfact: number;
+  K: number;
+  T0: number;
+  smode: number;
+  Cell: number;
+  Wd: number;
+  Ht: number;
+  pass1: number;
+  loopcnt: number;
+}
+
+/** Module-level mutable state, mirroring the C static. @see tlayout.c:parms */
+export const parms: TParms = {
+  useGrid: 0, useNew: 0, seed: 0, numIters: 0, maxIters: 0, unscaled: 0,
+  C: 0, Tfact: 0, K: 0, T0: 0, smode: 0, Cell: 0, Wd: 0, Ht: 0,
+  pass1: 0, loopcnt: 0,
+};
+
+/** Linear cooling schedule. @see lib/fdpgen/tlayout.c:cool */
+export function cool(t: number): number {
+  return parms.T0 * (parms.maxIters - t) / parms.maxIters;
+}
+
+/** @see lib/fdpgen/tlayout.c:reset_params */
+export function resetParams(): void {
+  parms.T0 = -1.0;
+}
+
+// ---------------------------------------------------------------------------
+// setSeed — parse the "start" attribute
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the graph "start" attribute into an init mode and seed.
+ * (The TS neato setSeed has a different shape; this is the C original.)
+ *
+ * When INIT_RANDOM is selected without a numeric seed, C uses
+ * time(NULL); Date.now() seconds substitute (non-deterministic in C
+ * too, so parity is unaffected).
+ *
+ * @see lib/neatogen/neatoinit.c:setSeed (15.0.0)
+ */
+export function setSeedFdp(
+  g: Graph,
+  dflt: number,
+  seedRef: { value: number },
+): number {
+  const p = aggetGraph(g, 'start');
+  if (p === undefined || p === '') return dflt;
+  const { init, rest } = classifyStart(p, dflt);
+  if (init === INIT_RANDOM) {
+    const m = /^-?[0-9]+/.exec(rest);
+    if (m === null) {
+      seedRef.value = Math.floor(Date.now() / 1000);
+    } else {
+      seedRef.value = parseInt(m[0], 10);
+    }
+  }
+  return init;
+}
+
+/**
+ * Classify the "start" value prefix (self/regular/random keyword or a
+ * bare numeric seed). @see lib/neatogen/neatoinit.c:setSeed
+ */
+export function classifyStart(
+  p: string,
+  dflt: number,
+): { init: number; rest: string } {
+  if (/^[0-9]/.test(p)) return { init: INIT_RANDOM, rest: p };
+  if (!/^[a-zA-Z]/.test(p)) return { init: dflt, rest: p };
+  if (p.startsWith('self')) return { init: INIT_SELF, rest: p.slice(4) };
+  if (p.startsWith('regular')) return { init: INIT_REGULAR, rest: p.slice(7) };
+  if (p.startsWith('random')) return { init: INIT_RANDOM, rest: p.slice(6) };
+  return { init: dflt, rest: p };
+}
+
+// ---------------------------------------------------------------------------
+// fdp_initParams / init_params
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialize parameters from the root graph's attributes.
+ * @see lib/fdpgen/tlayout.c:fdp_initParams
+ */
+export function fdpInitParams(g: Graph): void {
+  parms.useGrid = fdpParms.useGrid;
+  parms.useNew = fdpParms.useNew;
+  parms.numIters = fdpParms.numIters;
+  parms.unscaled = fdpParms.unscaled;
+  parms.Cell = DFLT_CELL;
+  parms.C = fdpParms.C;
+  parms.Tfact = fdpParms.Tfact;
+  parms.maxIters = lateInt(g.attrs.get('maxiter'), DFLT_MAX_ITERS, 0);
+  fdpParms.K = parms.K = lateDouble(g.attrs.get('K'), DFLT_K, 0.0);
+  if (fdpParms.T0 === -1.0) {
+    parms.T0 = lateDouble(g.attrs.get('T0'), -1.0, 0.0);
+  } else {
+    parms.T0 = fdpParms.T0;
+  }
+  resolveSeed(g);
+
+  parms.pass1 = Math.trunc(parms.unscaled * parms.maxIters / 100);
+
+  if (parms.useGrid) {
+    if (parms.Cell <= 0.0) parms.Cell = 3 * parms.K;
+  }
+}
+
+/** Seed/smode resolution block of fdp_initParams. @see tlayout.c:168-174 */
+function resolveSeed(g: Graph): void {
+  parms.seed = DFLT_SEED;
+  const seedRef = { value: parms.seed };
+  parms.smode = setSeedFdp(g, DFLT_SMODE, seedRef);
+  parms.seed = seedRef.value;
+  if (parms.smode === INIT_SELF) {
+    // C: agwarningf + T_seed = DFLT_smode (verbatim, including the
+    // smode-constant-into-seed assignment)
+    parms.seed = DFLT_SMODE;
+  }
+}
+
+/**
+ * Set parameters for the expansion phase from the initial-layout
+ * parameters; auto-derive T0 from graph size when unset.
+ * @returns whether resetParams must be called after this layout pass
+ * @see lib/fdpgen/tlayout.c:init_params
+ */
+export function initParams(g: Graph, xpms: XParams): boolean {
+  let ret = false;
+
+  if (parms.T0 === -1.0) {
+    const nnodes = g.nodes.size;
+    parms.T0 = parms.Tfact * parms.K * Math.sqrt(nnodes) / 5;
+    ret = true;
+  }
+
+  xpms.T0 = cool(parms.pass1);
+  xpms.K = parms.K;
+  xpms.C = parms.C;
+  xpms.numIters = parms.maxIters - parms.pass1;
+
+  if (parms.numIters >= 0) {
+    if (parms.numIters <= parms.pass1) {
+      parms.loopcnt = parms.numIters;
+      xpms.loopcnt = 0;
+    } else if (parms.numIters <= parms.maxIters) {
+      parms.loopcnt = parms.pass1;
+      xpms.loopcnt = parms.numIters - parms.pass1;
+    }
+  } else {
+    parms.loopcnt = parms.pass1;
+    xpms.loopcnt = xpms.numIters;
+  }
+  return ret;
+}