@knowvah/dot-engine 2.1.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowvah/dot-engine",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Faithful TypeScript port of Graphviz (dot, neato, fdp, sfdp, circo, twopi, osage, patchwork) — no C: no native binary, no WASM. Oracle-verified against the C implementation, runs in the browser.",
   "keywords": [
     "graphviz",
@@ -76,10 +76,12 @@
     "docs:brand": "node docs-site/copy-brand-assets.mjs",
     "docs:copy-reports": "node docs-site/copy-reports.mjs",
     "docs:copy-goldens": "node docs-site/copy-goldens.mjs",
+    "docs:i18n-status": "node scripts/docs-i18n-status.mjs",
+    "docs:i18n-hashes": "node scripts/docs-i18n-status.mjs --write-hashes",
     "docs:api": "typedoc",
-    "docs:dev": "npm run docs:brand && npm run docs:copy-reports && npm run docs:copy-goldens && npm run docs:api && vitepress dev docs-site",
+    "docs:dev": "npm run docs:brand && npm run docs:copy-reports && npm run docs:copy-goldens && npm run docs:i18n-hashes && npm run docs:api && vitepress dev docs-site",
     "predocs:build": "npm run parser:regen",
-    "docs:build": "npm run docs:brand && npm run docs:copy-reports && npm run docs:copy-goldens && npm run docs:api && vitepress build docs-site",
+    "docs:build": "npm run docs:brand && npm run docs:copy-reports && npm run docs:copy-goldens && npm run docs:i18n-hashes && npm run docs:api && vitepress build docs-site",
     "docs:preview": "vitepress preview docs-site",
     "release": "semantic-release",
     "publish:check": "npm run typecheck && npm run build && npm pack --dry-run",

package/src/common/libm-hypot.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * `hypot(a, b)` as the native build host's libm computes it, bit for bit.
+ *
+ * Graphviz calls libm `hypot`; V8's `Math.hypot` and `sqrt(a*a + b*b)` each
+ * round differently in the last bit for some inputs, and fdp's force loop
+ * amplifies one-ulp differences into visibly different layouts. The reference
+ * build's libm (macOS arm64 libSystem) matches this model exactly on 400k
+ * sampled inputs, including subnormal, near-overflow, zero, inf and NaN
+ * operands: order the magnitudes, rescale by 2^∓600 outside [2^-500, 2^500],
+ * then `sqrt(fma(small, small, big*big))`. It is within one ulp of the
+ * correctly rounded result (glibc's hypot can differ in that last bit).
+ *
+ * @see docs/known-divergences.md (host libm)
+ */
+
+import { fma } from './fma.js';
+
+/** Rescale thresholds and factor of the reference libm. */
+const BIG = 2 ** 500;
+const SMALL = 2 ** -500;
+const SCALE_UP = 2 ** 600;
+const SCALE_DOWN = 2 ** -600;
+
+/** libm `hypot(a, b)` of the native build host. */
+export function libmHypot(a: number, b: number): number {
+  if (a === Infinity || a === -Infinity || b === Infinity || b === -Infinity) return Infinity;
+  let x = Math.abs(a);
+  let y = Math.abs(b);
+  if (x < y) [x, y] = [y, x];
+  if (x > BIG) return core(x * SCALE_DOWN, y * SCALE_DOWN) * SCALE_UP;
+  if (x < SMALL) return core(x * SCALE_UP, y * SCALE_UP) * SCALE_DOWN;
+  return core(x, y);
+}
+
+/** sqrt(y·y + x·x) with the y·y product fused (x ≥ y ≥ 0). */
+function core(x: number, y: number): number {
+  return Math.sqrt(fma(y, y, x * x));
+}

package/src/common/poly-sizing.ts

@@ -23,6 +23,7 @@ import { STAR, CYLINDER } from './shapeData.js';
 import { starVertices } from './poly-vertices.js';
 import { fma } from './fma.js';
 import { RADIANS } from './arith.js';
+import { libmHypot } from './libm-hypot.js';
 
 /** Whitespace in points around labels / between peripheries. @see lib/common/const.h:GAP */
 export const GAP = 4;
@@ -277,16 +278,15 @@ export interface PolyGeom {
 
 /** Distort, skew, orient, and scale one unit vertex. @see shapes.c:poly_init */
 function transformUnitVertex(R: Point, g: PolyGeom, c: { skewdist: number; gdistortion: number; gskew: number }, bb: Point): Point {
-  const D = { x: R.x * (c.skewdist + R.y * c.gdistortion) + R.y * c.gskew, y: R.y };
+  // clang -ffp-contract=on fuses both multiply-adds of this one statement
+  // (the first product of the outer sum, as elsewhere in the port).
+  const D = { x: fma(R.x, fma(R.y, c.gdistortion, c.skewdist), R.y * c.gskew), y: R.y };
   const alpha = RADIANS(g.orientation) + Math.atan2(D.y, D.x);
-  // C uses libm hypot(D.x, D.y). V8's Math.hypot is a scaled algorithm that
-  // returns a result 1 ULP off from libm hypot for in-range polygon vertices
-  // (e.g. hypot(0.35355…, 0.35355…): libm = 0.5 exactly, Math.hypot = 0.5+1ULP),
-  // whereas the naive sqrt(x²+y²) reproduces libm's value bit-for-bit here.
-  // That ULP inflated ND_ht by ~7e-15, and pack.c genPoly's GRID(=ceil) rounded
-  // an exactly-on-boundary component height up a cell, reordering polyomino
-  // packing and swapping two circo/osage components. @see shapes.c:poly_init
-  const r = Math.sqrt(D.x * D.x + D.y * D.y);
+  // C uses libm hypot(D.x, D.y); libmHypot reproduces the host libm bit for bit.
+  // Neither V8's Math.hypot (hypot(0.35355339059327379, same) = 0.5+1ULP, which once
+  // inflated ND_ht by ~7e-15 and swapped two packed circo/osage components) nor
+  // sqrt(x²+y²) (off on e.g. the orientation=20 box) does. @see shapes.c:poly_init
+  const r = libmHypot(D.x, D.y);
   return { x: r * Math.cos(alpha) * bb.x, y: r * Math.sin(alpha) * bb.y };
 }
 
@@ -303,7 +303,7 @@ export function polygonVertices(
   const sectorangle = (2 * Math.PI) / g.sides;
   const sidelength = Math.sin(sectorangle / 2);
   const c = {
-    skewdist: Math.hypot(Math.abs(g.distortion) + Math.abs(g.skew), 1),
+    skewdist: libmHypot(Math.abs(g.distortion) + Math.abs(g.skew), 1),
     gdistortion: (g.distortion * SQRT2) / Math.cos(sectorangle / 2),
     gskew: g.skew / 2,
   };

package/src/layout/fdp/derive.ts

@@ -21,6 +21,7 @@ import { Node } from '../../model/node.js';
 import { Edge } from '../../model/edge.js';
 import type { Box } from '../../model/geom.js';
 import { doGraphLabel } from '../dot/graph-label.js';
+import { nodesInSeq } from '../dot/decomp.js';
 import { layoutMeasurer } from '../../common/nodeinit.js';
 import { inputscaleDivisor } from '../../common/utils-inputscale.js';
 import {
@@ -145,7 +146,9 @@ function deriveClusterNodes(g: Graph, dg: Graph, infop: LayoutInfo): void {
  * @see layout.c:deriveGraph (remaining-nodes loop)
  */
 function deriveRealNodes(g: Graph, dg: Graph): boolean {
-  for (const n of g.nodes.values()) {
+  // agfstnode/agnxtnode: a cluster subgraph iterates in node sequence order,
+  // not statement order; it fixes derived-node creation (and so id) order.
+  for (const n of nodesInSeq(g)) {
     if (getDnode(n) !== null) continue;
     const par = getParent(n);
     if (par !== null && par !== gdata(g).parent) {
@@ -195,7 +198,7 @@ function deriveEdge(dg: Graph, byPair: Map<string, Edge>, tl: Node, hd: Node): E
 
 /** Derived edges. @see layout.c:deriveGraph (edge loop) */
 function deriveEdges(g: Graph, dg: Graph, byPair: Map<string, Edge>): void {
-  for (const n of g.nodes.values()) {
+  for (const n of nodesInSeq(g)) { // agfstnode order, as in deriveRealNodes
     const tl = getDnode(n)!;
     for (const e of n.outEdges(g)) {
       const hd = getDnode(e.head)!;

package/src/layout/fdp/fdp-model.ts

@@ -4,11 +4,11 @@
  * fdp engine data model — gdata, dndata, bport_t, xparams, and the
  * accessor macros of the C private interface.
  *
- * Spec read at the 15.0.0 tag (post-tag fdpgen commits add an Mlimit
- * branch and float reorderings the golden refs do not have).
+ * Matches Graphviz after 15.0.0 (fdpParms.Mlimit lives in
+ * tlayout-parms.ts).
  *
- * @see lib/fdpgen/fdp.h (15.0.0)
- * @see lib/fdpgen/xlayout.h (15.0.0)
+ * @see lib/fdpgen/fdp.h
+ * @see lib/fdpgen/xlayout.h
  */
 
 import type { Graph } from '../../model/graph.js';

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

@@ -18,6 +18,7 @@ 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 { fma } from '../../common/fma.js';
 import {
   type Bport,
   dndata,
@@ -53,8 +54,9 @@ function placeByNeighbors(g: Graph, np: Node, ctr: Point): void {
     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;
+    // contracted (-ffp-contract=on): fmadd of the first product
+    np.info.pos![0] = fma(0.98, p.x, 0.1 * ctr.x);
+    np.info.pos![1] = fma(0.9, p.y, 0.1 * ctr.y);
   } else {
     const angle = Math.PI * 2.0 * drand48();
     const radius = 0.9 * drand48();
@@ -76,8 +78,8 @@ function averagePlacedNeighbors(g: Graph, np: Node, p: Point): number {
     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);
+      p.x = fma(p.x, cnt, op.info.pos![0]!) / (cnt + 1); // contracted
+      p.y = fma(p.y, cnt, op.info.pos![1]!) / (cnt + 1);
     } else {
       p.x = op.info.pos![0]!;
       p.y = op.info.pos![1]!;
@@ -162,8 +164,8 @@ function sizeBoundary(width: number, height: number): void {
 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;
+    np.info.pos![0] = fma(parms.Wd, Math.cos(port.alpha), ctr.x); // contracted
+    np.info.pos![1] = fma(parms.Ht, Math.sin(port.alpha), ctr.y);
     dndata(np).pinned = P_SET;
   }
   for (const np of g.nodes.values()) {

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

@@ -9,7 +9,7 @@
  *
  * @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
+ * @see lib/common/globals.c — fdpParms defaults
  */
 
 import type { Graph } from '../../model/graph.js';
@@ -41,7 +41,7 @@ export const INIT_RANDOM = 2;
 const DFLT_SMODE = INIT_RANDOM;
 
 // ---------------------------------------------------------------------------
-// fdp_parms defaults — @see lib/common/globals.c (15.0.0)
+// fdp_parms defaults — @see lib/common/globals.c
 // ---------------------------------------------------------------------------
 
 /**
@@ -61,6 +61,9 @@ export const fdpParms = {
   Tfact: 1.0,
   K: -1.0,
   T0: -1.0,
+  /** Distance beyond which repulsion is 0; HUGE_VAL unless `dot -Lm` (no library
+   *  equivalent). @see lib/fdpgen/fdp.h:fdpParms_s.Mlimit */
+  Mlimit: Infinity,
 };
 
 // ---------------------------------------------------------------------------

package/src/layout/fdp/tlayout.ts

@@ -4,9 +4,8 @@
  * fdp initial layout — grid-accelerated Fruchterman–Reingold on point
  * nodes with boundary ports.
  *
- * Spec read at the 15.0.0 tag: the post-tag tree reorders doRep floats
- * (hypot vs sqrt(x²·y²)) and adds an Mlimit cutoff; the golden refs are
- * 15.0.0 output, so neither is ported.
+ * Repulsion follows Graphviz after 15.0.0: doRep takes the hypot distance
+ * (the host libm's, see libm-hypot.ts) and honours the Mlimit cutoff.
  *
  * All math is double precision (unlike neato's float32 stress kernel).
  * Force-accumulation order is load-bearing: node iteration is the
@@ -16,13 +15,14 @@
  * Parameter state lives in tlayout-parms.ts; initial placement in
  * tlayout-init.ts.
  *
- * @see lib/fdpgen/tlayout.c (15.0.0)
+ * @see lib/fdpgen/tlayout.c
  */
 
 import type { Graph } from '../../model/graph.js';
 import type { Node } from '../../model/node.js';
 import type { Edge } from '../../model/edge.js';
 import { fma, fms } from '../../common/fma.js';
+import { libmHypot } from '../../common/libm-hypot.js';
 import { Grid, type Cell } from './grid.js';
 import {
   type Bport,
@@ -33,7 +33,7 @@ import {
   gdata,
   P_FIX,
 } from './fdp-model.js';
-import { parms, cool, initParams, resetParams } from './tlayout-parms.js';
+import { parms, cool, initParams, resetParams, fdpParms } from './tlayout-parms.js';
 import { initPositions } from './tlayout-init.js';
 import { crand } from '../../common/crand.js';
 
@@ -66,25 +66,26 @@ export function coincidentDelta(): { xdelta: number; ydelta: number } {
 }
 
 /**
- * Repulsive force = K²/d (useNew) or K²/d².
+ * Repulsive force = K²/d² (useNew) or K²/d, zero beyond Mlimit.
  * @see lib/fdpgen/tlayout.c:doRep
  */
 function doRep(
-  p: Node, q: Node, xdelta: number, ydelta: number, dist2: number,
+  p: Node, q: Node, xdelta: number, ydelta: number, dist: number,
 ): void {
   let force: number;
 
-  if (dist2 === 0.0) {
-    const d = coincidentDelta();
+  if (!(dist > 0)) {
+    const d = coincidentDelta(); // C re-rolls rand() until hypot > 0
     xdelta = d.xdelta;
     ydelta = d.ydelta;
-    dist2 = fma(xdelta, xdelta, ydelta * ydelta);
+    dist = libmHypot(xdelta, ydelta);
   }
-  if (parms.useNew) {
-    const dist = Math.sqrt(dist2);
-    force = parms.K * parms.K / (dist * dist2);
+  if (dist > fdpParms.Mlimit) {
+    force = 0;
+  } else if (parms.useNew) {
+    force = parms.K * parms.K / (dist * dist * dist);
   } else {
-    force = parms.K * parms.K / dist2;
+    force = parms.K * parms.K / (dist * dist);
   }
   if (isPort(p) && isPort(q)) force *= 10.0;
   const dq = disp(q);
@@ -100,7 +101,7 @@ function doRep(
 function applyRep(p: Node, q: Node): void {
   const xdelta = q.info.pos![0]! - p.info.pos![0]!;
   const ydelta = q.info.pos![1]! - p.info.pos![1]!;
-  doRep(p, q, xdelta, ydelta, fma(xdelta, xdelta, ydelta * ydelta));
+  doRep(p, q, xdelta, ydelta, libmHypot(xdelta, ydelta));
 }
 
 /** @see lib/fdpgen/tlayout.c:doNeighbor */
@@ -111,8 +112,8 @@ function doNeighbor(grid: Grid, i: number, j: number, nodes: Node[]): void {
     for (const q of cellp.nodes) {
       const xdelta = q.info.pos![0]! - p.info.pos![0]!;
       const ydelta = q.info.pos![1]! - p.info.pos![1]!;
-      const dist2 = fma(xdelta, xdelta, ydelta * ydelta);
-      if (dist2 < parms.Cell * parms.Cell) doRep(p, q, xdelta, ydelta, dist2);
+      const dist = libmHypot(xdelta, ydelta);
+      if (dist < parms.Cell) doRep(p, q, xdelta, ydelta, dist);
     }
   }
 }

package/src/layout/fdp/xlayout.ts

@@ -4,8 +4,8 @@
  * fdp expansion layout: grow the point-node layout so sized nodes do
  * not overlap, by force iteration with overlap-aware repulsion.
  *
- * Spec read at the 15.0.0 tag (the post-tag Mlimit force cutoff is
- * deliberately NOT ported — the golden refs predate it).
+ * Follows Graphviz after 15.0.0: repulsion uses the hypot distance (the
+ * host libm's, see libm-hypot.ts) and the Mlimit cutoff.
  *
  * The default overlap attribute is "9:prism": up to 9 x_layout tries,
  * then removeOverlapAs with the remaining mode. x_layout does NOT always
@@ -14,7 +14,7 @@
  * fdpAdjust, the scale family via scAdjust. On the GTS reference build
  * overlap=false resolves to AM_PRISM (value 1000), not a no-op.
  *
- * @see lib/fdpgen/xlayout.c (15.0.0)
+ * @see lib/fdpgen/xlayout.c
  */
 
 import { RenderError } from '../../errors.js';
@@ -31,6 +31,9 @@ import {
   P_PIN,
 } from './fdp-model.js';
 import { coincidentDelta } from './tlayout.js';
+import { fdpParms } from './tlayout-parms.js';
+import { libmHypot } from '../../common/libm-hypot.js';
+import { fma, fms } from '../../common/fma.js';
 import { normalizeG } from './normalize.js';
 import { simpleScale } from '../neato/simple-scale.js';
 
@@ -76,7 +79,7 @@ function ht2(n: Node): number {
 
 /** Expanded radius of n. @see lib/fdpgen/xlayout.c:RAD */
 function rad(n: Node): number {
-  return Math.hypot(wd2(n), ht2(n));
+  return libmHypot(wd2(n), ht2(n));
 }
 
 /**
@@ -129,31 +132,32 @@ function cntOverlaps(g: Graph): number {
 // ---------------------------------------------------------------------------
 
 /**
- * Overlap-aware repulsion; returns 1 if the pair overlaps.
- * The delta/dist2 computation of C's applyRep is inlined here; the
- * C doRep/applyRep split exists for the rand() re-roll loop on
- * coincident nodes (coincidentDelta), shared with tlayout.
+ * Overlap-aware repulsion; returns 1 if the pair overlaps. Zero beyond
+ * Mlimit. C's applyRep (delta + hypot) is inlined; its doRep re-rolls rand()
+ * deltas while the distance is not positive (coincidentDelta).
  * @see lib/fdpgen/xlayout.c:doRep
  * @see lib/fdpgen/xlayout.c:applyRep
  */
 function applyRep(p: Node, q: Node, rs: RepStrength): number {
   let xdelta = q.info.pos![0]! - p.info.pos![0]!;
   let ydelta = q.info.pos![1]! - p.info.pos![1]!;
-  let dist2 = xdelta * xdelta + ydelta * ydelta;
-  if (dist2 === 0.0) {
+  let dist = libmHypot(xdelta, ydelta);
+  if (!(dist > 0)) {
     const d = coincidentDelta();
     xdelta = d.xdelta;
     ydelta = d.ydelta;
-    dist2 = xdelta * xdelta + ydelta * ydelta;
+    dist = libmHypot(xdelta, ydelta);
   }
   const ov = overlap(p, q) ? 1 : 0;
-  const force = ov ? rs.ov / dist2 : rs.nonov / dist2;
+  let force = ov ? rs.ov / (dist * dist) : rs.nonov / (dist * dist);
+  if (dist > fdpParms.Mlimit) force = 0;
   const dq = disp(q);
   const dp = disp(p);
-  dq[0] += xdelta * force;
-  dq[1] += ydelta * force;
-  dp[0] -= xdelta * force;
-  dp[1] -= ydelta * force;
+  // arm64 contraction (-ffp-contract=on): DISP ± delta·force are fmadd/fmsub
+  dq[0] = fma(xdelta, force, dq[0]!);
+  dq[1] = fma(ydelta, force, dq[1]!);
+  dp[0] = fms(xdelta, force, dp[0]!);
+  dp[1] = fms(ydelta, force, dp[1]!);
   return ov;
 }
 
@@ -165,16 +169,16 @@ function applyAttr(p: Node, q: Node): void {
   if (overlap(p, q)) return;
   const xdelta = q.info.pos![0]! - p.info.pos![0]!;
   const ydelta = q.info.pos![1]! - p.info.pos![1]!;
-  const dist = Math.hypot(xdelta, ydelta);
+  const dist = libmHypot(xdelta, ydelta);
   const din = rad(p) + rad(q);
   const dout = dist - din;
   const force = dout * dout / ((xParams.K + din) * dist);
   const dq = disp(q);
   const dp = disp(p);
-  dq[0] -= xdelta * force;
-  dq[1] -= ydelta * force;
-  dp[0] += xdelta * force;
-  dp[1] += ydelta * force;
+  dq[0] = fms(xdelta, force, dq[0]!);
+  dq[1] = fms(ydelta, force, dq[1]!);
+  dp[0] = fma(xdelta, force, dp[0]!);
+  dp[1] = fma(ydelta, force, dp[1]!);
 }
 
 // ---------------------------------------------------------------------------
@@ -204,7 +208,7 @@ function moveNodes(g: Graph, temp: number): void {
     if (dndata(n).pinned === P_PIN) continue;
     const dx = disp(n)[0];
     const dy = disp(n)[1];
-    const len2 = dx * dx + dy * dy;
+    const len2 = fma(dx, dx, dy * dy); // contracted, as in tlayout
     if (len2 < temp2) {
       n.info.pos![0]! += dx;
       n.info.pos![1]! += dy;