@knowvah/dot-engine 1.9.0 → 2.0.1

package/src/layout/neato/index.ts

@@ -2,7 +2,7 @@
 /**
  * Neato layout engine entry point.
  *
- * Wires together neatoInitNode, setSeed, solveModel, removeOverlap,
+ * Wires together neatoInitNode, setSeed, solveModel, adjustNodes,
  * splineEdges, neatoTranslate, and neatoSetAspect into the full neato
  * layout pipeline, and exports NEATO_LAYOUT_ENGINE for registration with
  * GvcContext.
@@ -14,28 +14,26 @@
 import type { Graph } from '../../model/graph.js';
 import type { LayoutEngine } from '../../gvc/context.js';
 import {
+  MODE_KK,
   neatoInitNode,
   userPos,
   solveModel,
   neatoCleanup,
-  MODE_KK,
-  MODE_MAJOR,
-  MODE_HIER,
-  MODE_IPSEP,
-  MODE_SGD,
   MODEL_SHORTPATH,
   MODEL_CIRCUIT,
   MODEL_SUBSET,
   MODEL_MDS,
 } from './init.js';
-import { removeOverlap } from './overlap.js';
+import { neatoMode } from './start.js';
 import { adjustNodesFull } from './fdp-adjust.js';
 import { splineEdgesShifted, EDGETYPE_LINE } from './splines.js';
 import { setEdgeTypeFromAttr } from '../dot/index.js';
 import {
   pccomps,
   computeSubgraphBB,
+  getPack,
   getPackInfo,
+  getPackModeInfo,
   packGraphs,
   PackMode,
   type PackInfo,
@@ -43,7 +41,7 @@ import {
 import { CL_OFFSET } from '../twopi/pipeline.js';
 import { isACluster } from '../dot/rank.js';
 import { doGraphLabel } from '../dot/graph-label.js';
-import { graphInit, DEFAULT_NODESEP_POINTS } from '../../common/graph-init.js';
+import { graphInit } from '../../common/graph-init.js';
 import { placeGraphLabel } from '../dot/position-bbox.js';
 import { gvPostprocess } from '../../common/postproc.js';
 import { layoutMeasurer } from '../../common/nodeinit.js';
@@ -62,25 +60,14 @@ export {
 // Mode parsing
 // ---------------------------------------------------------------------------
 
-/** Map from mode string to numeric constant. @see lib/neatogen/neato.h */
-const MODE_MAP: Record<string, number> = {
-  KK: MODE_KK,
-  major: MODE_MAJOR,
-  hier: MODE_HIER,
-  ipsep: MODE_IPSEP,
-  sgd: MODE_SGD,
-};
-
 /**
- * Parse `g.info.mode` string into a numeric mode constant.
- * Defaults to MODE_MAJOR when unset or unrecognised.
+ * Parse the root `mode` attribute into a numeric mode constant (C neatoMode).
+ * Defaults to MODE_MAJOR when unset; warns and defaults on an unknown value.
  *
- * @see lib/neatogen/neato.h:neatoMode
+ * @see lib/neatogen/neatoinit.c:neatoMode
  */
 export function parseMode(g: Graph): number {
-  const s = g.info.mode;
-  if (!s) return MODE_MAJOR;
-  return MODE_MAP[s] ?? MODE_MAJOR;
+  return neatoMode(g);
 }
 
 // ---------------------------------------------------------------------------
@@ -113,39 +100,15 @@ export function parseModel(g: Graph): number {
 // ---------------------------------------------------------------------------
 
 /**
- * Apply VPSC overlap removal unless `g.info.overlap === 'false'`.
+ * Remove node overlaps per the `overlap` attribute: C's removeOverlapWith
+ * dispatch (prism, scale family, oscale, ortho*, portho*, vpsc, voronoi) for
+ * every mode, as neato_layout's adjustNodes call does.
  *
- * @see lib/neatogen/neatoinit.c:neato_layout (removeOverlapWith call)
+ * @see lib/neatogen/neatoinit.c:neato_layout (adjustNodes call)
+ * @see lib/neatogen/adjust.c:removeOverlapWith
  */
 export function maybeRemoveOverlap(g: Graph): void {
-  // C: graphAdjustMode defaults to AM_NONE — no overlap attr means no
-  // overlap removal ("overlap: none"). VPSC runs only on request.
-  const overlap = g.attrs.get('overlap');
-  if (overlap === undefined || overlap === 'true') return;
-  // C removeOverlapWith dispatches by adjust mode. `overlap=false` resolves to
-  // AM_PRISM (getAdjustMode's boolean fallback lands on adjustMode[1] on a
-  // GTS+SFDP build), `overlap=scale/scalexy/compress` to the scale family, only
-  // `overlap=vpsc` to VPSC. Previously neato hardcoded VPSC for ALL of these,
-  // under-scaling every overlap=false graph (bb ~0.4-0.8x the oracle) and
-  // scaling scale-mode graphs wrong. adjustNodesFull is the ported
-  // removeOverlapWith body (PRISM via fdpAdjust + scale via scAdjust); VPSC is
-  // the one mode it does not cover. @see lib/neatogen/adjust.c:removeOverlapWith
-  if (overlap !== 'vpsc') {
-    adjustNodesFull(g);
-    return;
-  }
-  const nodes = Array.from(g.nodes.values());
-  // Separation is DELIBERATELY the *default* nodesep, not GD_nodesep(g). C's
-  // overlap removal derives its padding from `sep`/DFLT_MARGIN (adjust.c:591-600
-  // sepFactor) and never reads GD_nodesep — that field is used only by
-  // makeSelfArcs (neatosplines.c:673) and routespl.c:1006. Before graph_init was
-  // consolidated, GD_nodesep was unset under neato at this point, so this site
-  // always saw the 18pt default; now that graphInit parses `nodesep` for every
-  // engine (as C does), reading it here would silently change the VPSC
-  // separation on graphs that set both `nodesep` and `overlap` (corpus: 1554,
-  // 2242) — a divergence C does not have. Pinned to the default it always used.
-  const nodesep = DEFAULT_NODESEP_POINTS / 72; // points → inches
-  removeOverlap(nodes, { x: nodesep / 2, y: nodesep / 2 });
+  adjustNodesFull(g);
 }
 
 // ---------------------------------------------------------------------------
@@ -205,7 +168,9 @@ export function neatoLayout(g: Graph): void {
 
   // C uses pccomps (pin-aware): components with a pinned node are collected
   // first (index 0) so the packer can hold them fixed. @see neatoinit.c:1391
-  const { graphs: comps, pinned } = pccomps(g, '_neato_cc');
+  const { graphs: comps, pinned } = neatoPack(g, mode) >= 0
+    ? pccomps(g, '_neato_cc')
+    : { graphs: [g], pinned: false };
   if (comps.length > 1) {
     layoutComponents(g, comps, mode, model, pinned);
   } else {
@@ -227,6 +192,23 @@ export function neatoLayout(g: Graph): void {
   gvPostprocess(g);
 }
 
+/**
+ * C's Pack decision: unset `pack` with no `packmode` packs (CL_OFFSET) unless
+ * layoutMode is MODE_KK (0); a set `packmode` always packs. Negative means the
+ * whole graph is laid out at once.
+ * @see lib/neatogen/neatoinit.c:1371-1383 (neato_layout)
+ */
+function neatoPack(g: Graph, layoutMode: number): number {
+  const pinfo: PackInfo = {
+    aspect: 1, sz: 0, margin: CL_OFFSET, doSplines: false,
+    mode: PackMode.Undef, fixed: null, vals: null, flags: 0,
+  };
+  const mode = getPackModeInfo(g, PackMode.Undef, pinfo);
+  const pack = getPack(g, -1, CL_OFFSET);
+  if (mode === PackMode.Undef) return pack < 0 && layoutMode !== MODE_KK ? CL_OFFSET : pack;
+  return pack < 0 ? CL_OFFSET : pack;
+}
+
 /**
  * Register direct cluster subgraphs: build their labels and tight
  * member bounding boxes for emission.

package/src/layout/neato/init.ts

@@ -21,7 +21,10 @@ import {
   MODEL_SUBSET as STRESS_MODEL_SUBSET,
 } from './stress.js';
 import { sgdLayout } from './sgd.js';
-import { srand48 } from '../../common/random.js';
+import { kkNeato } from './kk.js';
+import { checkStart, assertSupported, parseStart, INIT_RANDOM, INIT_REGULAR } from './start.js';
+
+export { checkStart };
 import { mapbool } from '../dot/rank.js';
 import {
   computeApspPacked,
@@ -30,6 +33,7 @@ import {
   OPT_EXP_FLAG,
 } from './stress-kernel.js';
 import { lateDouble } from '../../common/nodeinit.js';
+import { inputscaleDivisor } from '../../common/utils-inputscale.js';
 import { parseNeatoDrawing, neatoSetAspectRatio } from './set-aspect.js';
 
 // ---------------------------------------------------------------------------
@@ -85,15 +89,10 @@ export function neatoInitNode(n: Node, dim = DFLT_DIM): void {
     n.info.pos = pos;
   }
   if (n.info.UF_size === undefined) n.info.UF_size = 1;
-  // C neato_init_node has NO size defaulting (neatoinit.c:60-66) — after
-  // common_init_node, ND_width is always written (late_double clamps a 0
-  // attr to the 0.75 default; every initfn assigns). The port's NodeInfo
-  // zero-initializes width/height (calloc mirror) and two port-only paths
-  // leave them at that unset-0 (no-measurer initNodeDefaults; poly-null
-  // custom/epsf shapes — C gives customs box geometry, a modeling gap
-  // flagged in the journal), so a fallback is still needed. The ONE case
-  // where 0 is a legitimate post-init size is shape=plain (poly_init
-  // IS_PLAIN, shapes.c:1962) — never clobber it.
+  // C neato_init_node has no size defaulting (neatoinit.c:60-66); the port's
+  // zero-initialised width/height need a fallback on two port-only paths
+  // (no-measurer initNodeDefaults, poly-null custom/epsf shapes). The one
+  // legitimate post-init 0 is shape=plain (poly_init IS_PLAIN) — never clobber it.
   const plainShaped = (n.info.shape as ShapeDesc | undefined)?.name === 'plain';
   if (!n.info.width && !plainShaped) n.info.width = 0.75;
   if (!n.info.height && !plainShaped) n.info.height = 0.5;
@@ -109,10 +108,8 @@ export function neatoInitNode(n: Node, dim = DFLT_DIM): void {
  * majorization starts from the input layout instead of a random init; a `!`
  * suffix or `pin=true` additionally sets info.pinned (P_PIN → isFixed).
  *
- * PSinputscale (the `inputscale` attr) is not tracked — the suite has
- * PSinputscale <= 0, so positions stay in points exactly as native leaves them
- * (a `pos="27,42"` seeds (27,42), which orthog1 then centres). Must run AFTER
- * neatoInitNode, which zeroes info.pos.
+ * `pos` is divided by PSinputscale when > 0 (neatoinit.c:90-95). Must run
+ * AFTER neatoInitNode, which zeroes info.pos.
  * @see lib/neatogen/neatoinit.c:user_pos
  */
 export function userPos(n: Node): boolean {
@@ -122,7 +119,8 @@ export function userPos(n: Node): boolean {
   const num = '(-?\\d+(?:\\.\\d+)?(?:[eE][+-]?\\d+)?)';
   const m = new RegExp(`^\\s*${num}\\s*,\\s*${num}(.?)`).exec(p);
   if (m === null) return false; // C agerrorf: malformed pos, non-fatal
-  n.info.pos = [Number(m[1]), Number(m[2])];
+  const div = inputscaleDivisor(n.root);
+  n.info.pos = [Number(m[1]) / div, Number(m[2]) / div];
   n.info.posSet = true;
   const pin = n.attrs.get('pin');
   if (m[3] === '!' || (pin !== undefined && mapbool(pin))) n.info.pinned = true;
@@ -335,7 +333,7 @@ export function runMajorization(g: Graph, mode: number, model: number): void {
   const haveLen = graphHasLen(g);
   const vtx = makeGraphDataC(g, nodeList, haveLen);
   checkStart(g); // C: srand48(seed) immediately before initLayout draws
-  const maxi = mode === MODE_KK ? 0 : lateDouble(g.attrs.get('maxiter'), DFLT_ITERATIONS, 0);
+  const maxi = lateDouble(g.attrs.get('maxiter'), DFLT_ITERATIONS, 0);
   const epsilon = lateDouble(g.attrs.get('epsilon'), 1e-4, 0); // DFLT_TOLERANCE
   const Dij = haveLen ? computeWeightedApspPacked(vtx, n) : computeApspPacked(vtx, n);
   const dCoords = [new Float64Array(n), new Float64Array(n)];
@@ -355,22 +353,6 @@ export function graphHasLen(g: Graph): boolean {
   return false;
 }
 
-/**
- * Seed the RNG from the start attr; no attr means the default seed 1.
- * start=regular/self are not ported (no suite input uses them).
- * @see lib/neatogen/neatoinit.c:setSeed
- * @see lib/neatogen/neatoinit.c:checkStart
- */
-export function checkStart(g: Graph): void {
-  const p = g.root.attrs.get('start');
-  let seed = 1;
-  if (p !== undefined && /^\d/.test(p)) {
-    const v = parseInt(p, 10);
-    if (!Number.isNaN(v)) seed = v;
-  }
-  srand48(seed);
-}
-
 /**
  * Build the vtx_data adjacency in C's makeGraphData shape: per node,
  * out-edges then in-edges (agfstedge order), self entry at index 0,
@@ -414,10 +396,13 @@ export function makeGraphDataC(g: Graph, nodeList: Node[], haveLen: boolean): Vt
  */
 export function solveModel(g: Graph, mode: number, model: number): void {
   if (g.nodes.size < 2) return;
-  if (mode === MODE_SGD) { sgdLayout(g, model); return; }
-  if (mode === MODE_HIER || mode === MODE_IPSEP) {
-    const name = mode === MODE_HIER ? 'hier' : 'ipsep';
-    console.warn(`neato: mode ${name} not fully implemented; falling back to majorization`);
+  assertSupported(g, mode, model);
+  if (mode === MODE_KK) return kkNeato(g, g.nodes.size, model);
+  if (mode === MODE_SGD) {
+    // C initial_positions -> checkStart: regular positions are kept
+    if (parseStart(g.root.attrs.get('start'), INIT_RANDOM).init === INIT_REGULAR) checkStart(g);
+    sgdLayout(g, model);
+    return;
   }
   runMajorization(g, mode, model);
 }

package/src/layout/neato/kk-paths.ts

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Kamada-Kawai ideal-distance setup: Dijkstra over edge lengths with C's
+ * binary heap (`neato_enqueue`/`neato_dequeue`, `shortest_path`, `s1`,
+ * `make_spring`) and `mds_model`.
+ *
+ * The C keeps the heap, its size and the source node in file-statics and the
+ * per-node `ND_dist`/`ND_hops`/`ND_heapindex` in node records; here they live
+ * in one {@link PathState} per run (no module state), indexed by `ND_id`.
+ *
+ * @see lib/neatogen/stuff.c
+ */
+
+/** One neighbour of a node: its id and the edge's `ED_dist`. */
+export interface Neighbour {
+  readonly id: number;
+  readonly len: number;
+}
+
+/** Heap + per-node Dijkstra state. @see lib/neatogen/stuff.c (Heap, Heapsize) */
+export interface PathState {
+  readonly n: number;
+  /** `GD_dist` as a flat n*n matrix. */
+  readonly dist: Float64Array;
+  /** `agfstedge` neighbours of each node, in C's iteration order. */
+  readonly adj: readonly (readonly Neighbour[])[];
+  /** `Initial_dist`. */
+  readonly initialDist: number;
+  readonly heap: Int32Array;
+  heapSize: number;
+  /** `ND_heapindex` (-1 = not queued). */
+  readonly heapIndex: Int32Array;
+  /** `ND_dist`. */
+  readonly nd: Float64Array;
+  /** `ND_hops`. */
+  readonly hops: Int32Array;
+}
+
+/** Fresh path state for `n` nodes. @see lib/neatogen/stuff.c:shortest_path */
+export function newPathState(
+  n: number, dist: Float64Array, adj: readonly (readonly Neighbour[])[], initialDist: number,
+): PathState {
+  return {
+    n, dist, adj, initialDist,
+    heap: new Int32Array(n + 1), heapSize: 0,
+    heapIndex: new Int32Array(n).fill(-1),
+    nd: new Float64Array(n), hops: new Int32Array(n),
+  };
+}
+
+/** @see lib/neatogen/stuff.c:heapup */
+function heapUp(s: PathState, v: number): void {
+  for (let i = s.heapIndex[v]!, par: number; i > 0; i = par) {
+    par = (i - 1) >> 1;
+    const u = s.heap[par]!;
+    if (s.nd[u]! <= s.nd[v]!) break;
+    s.heap[par] = v;
+    s.heapIndex[v] = par;
+    s.heap[i] = u;
+    s.heapIndex[u] = i;
+  }
+}
+
+/** @see lib/neatogen/stuff.c:heapdown */
+function heapDown(s: PathState, v: number): void {
+  let i = s.heapIndex[v]!;
+  for (let left = 2 * i + 1; left < s.heapSize; left = 2 * i + 1) {
+    const right = left + 1;
+    const c = right < s.heapSize && s.nd[s.heap[right]!]! < s.nd[s.heap[left]!]! ? right : left;
+    const u = s.heap[c]!;
+    if (s.nd[v]! <= s.nd[u]!) break;
+    s.heap[c] = v;
+    s.heapIndex[v] = c;
+    s.heap[i] = u;
+    s.heapIndex[u] = i;
+    i = c;
+  }
+}
+
+/** @see lib/neatogen/stuff.c:neato_enqueue */
+function enqueue(s: PathState, v: number): void {
+  const i = s.heapSize++;
+  s.heapIndex[v] = i;
+  s.heap[i] = v;
+  if (i > 0) heapUp(s, v);
+}
+
+/** Returns -1 when empty (C: NULL). @see lib/neatogen/stuff.c:neato_dequeue */
+function dequeue(s: PathState): number {
+  if (s.heapSize === 0) return -1;
+  const rv = s.heap[0]!;
+  const i = --s.heapSize;
+  const v = s.heap[i]!;
+  s.heap[0] = v;
+  s.heapIndex[v] = 0;
+  if (i > 1) heapDown(s, v);
+  s.heapIndex[rv] = -1;
+  return rv;
+}
+
+/** @see lib/neatogen/stuff.c:make_spring */
+function makeSpring(s: PathState, u: number, v: number, f: number): void {
+  s.dist[u * s.n + v] = f;
+  s.dist[v * s.n + u] = f;
+}
+
+/** Single-source shortest paths from `src`. @see lib/neatogen/stuff.c:s1 */
+function s1(s: PathState, src: number): void {
+  s.nd.fill(s.initialDist);
+  s.nd[src] = 0;
+  s.hops[src] = 0;
+  enqueue(s, src);
+  for (let v = dequeue(s); v >= 0; v = dequeue(s)) {
+    if (v !== src) makeSpring(s, src, v, s.nd[v]!);
+    for (const { id: u, len } of s.adj[v]!) {
+      const f = s.nd[v]! + len;
+      if (s.nd[u]! <= f) continue;
+      s.nd[u] = f;
+      if (s.heapIndex[u]! >= 0) heapUp(s, u);
+      else {
+        s.hops[u] = s.hops[v]! + 1;
+        enqueue(s, u);
+      }
+    }
+  }
+}
+
+/** All-pairs shortest paths into `GD_dist`. @see lib/neatogen/stuff.c:shortest_path */
+export function shortestPath(s: PathState): void {
+  for (let v = 0; v < s.n; v++) s1(s, v);
+}
+
+/**
+ * Overwrite `GD_dist` with edge lengths. C indexes the matrix with `AGSEQ`
+ * (1-based), so the last node's row falls outside the n*n allocation (heap
+ * overflow in C); out-of-range writes are dropped here.
+ * @see lib/neatogen/neatoinit.c:mds_model
+ */
+export function mdsModel(
+  dist: Float64Array, n: number, edges: readonly { tailSeq: number; headSeq: number; len: number }[],
+): void {
+  for (const { tailSeq: i, headSeq: j, len } of edges) {
+    if (i === j) continue;
+    for (const k of [i * n + j, j * n + i]) if (k < dist.length) dist[k] = len;
+  }
+}

package/src/layout/neato/kk-solve.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Gaussian elimination with partial pivoting for the small Newton systems of
+ * Kamada-Kawai (`move_node`).
+ *
+ * @see lib/neatogen/solve.c
+ */
+
+/** Pivots below this make the system ill-conditioned. @see solve.c:solve */
+const MIN_PIVOT = 1.0e-10;
+
+/** @see lib/neatogen/solve.c:SWAP */
+function swap(x: Float64Array, i: number, j: number): void {
+  const t = x[i]!;
+  x[i] = x[j]!;
+  x[j] = t;
+}
+
+/** Returns false on an unusable pivot. Eliminates unknown `i`. */
+function eliminate(a: Float64Array, c: Float64Array, n: number, i: number): boolean {
+  let amax = 0.0;
+  let istar = 0;
+  for (let ii = i; ii < n; ii++) {
+    const dum = Math.abs(a[ii * n + i]!);
+    if (dum < amax) continue;
+    istar = ii;
+    amax = dum;
+  }
+  if (amax < MIN_PIVOT) return false;
+  for (let j = i; j < n; j++) swap(a, istar * n + j, i * n + j);
+  swap(c, istar, i);
+  for (let ii = i + 1; ii < n; ii++) {
+    const pivot = a[ii * n + i]! / a[i * n + i]!;
+    c[ii]! -= pivot * c[i]!;
+    for (let j = 0; j < n; j++) a[ii * n + j] = a[ii * n + j]! - pivot * a[i * n + j]!;
+  }
+  return true;
+}
+
+/**
+ * Solve a*b = c (a is n*n row-major). On success `a` and `c` are restored and
+ * `b` holds the solution; when ill-conditioned `b` is untouched. C prints
+ * "ill-conditioned" to stdout; a library has no stdout, so it is a warning.
+ * @see lib/neatogen/solve.c:solve
+ */
+export function solve(a: Float64Array, b: Float64Array, c: Float64Array, n: number): void {
+  const asave = Float64Array.from(a);
+  const csave = Float64Array.from(c);
+  let ok = true;
+  for (let i = 0; i < n - 1 && ok; i++) ok = eliminate(a, c, n, i);
+  if (!ok || Math.abs(a[n * n - 1]!) < MIN_PIVOT) {
+    console.warn('ill-conditioned');
+    return;
+  }
+  b[n - 1] = c[n - 1]! / a[n * n - 1]!;
+  for (let k = 0; k < n - 1; k++) {
+    const m = n - k - 2;
+    b[m] = c[m]!;
+    for (let j = m + 1; j < n; j++) b[m]! -= a[m * n + j]! * b[j]!;
+    b[m]! /= a[m * n + m]!;
+  }
+  c.set(csave);
+  a.set(asave);
+}