@graphty/webgpu-graph-algorithms 0.5.0 → 0.5.1

package/src/types/accelerator.ts

@@ -37,8 +37,14 @@ import type {
     KatzOptions,
     PageRankOptions,
 } from "./algorithms.js";
-import type { ForceAtlas2Stats, GpuLayoutSimulation, GpuLayoutTuning } from "./layout.js";
-import type { ForceAtlas2Options } from "./options.js";
+import type {
+    ForceAtlas2Stats,
+    FruchtermanReingoldStats,
+    GpuLayoutSimulation,
+    GpuLayoutTuning,
+    SpringElectricalStats,
+} from "./layout.js";
+import type { ForceAtlas2Options, FruchtermanReingoldOptions, SpringElectricalOptions } from "./options.js";
 
 // ---- the real @graphty/layout interfaces (spec 9.3, D27): imported at W1b, re-exported so the package's public
 // surface is unchanged and src/types/layout.ts keeps resolving them from here. `export type`, never a bare
@@ -86,7 +92,9 @@ export interface AcceleratorOptions {
 }
 
 /**
- * The injectable object (spec 3.3): P3's forceAtlas2, release and dispose, plus P7's seven algorithm members
+ * The injectable object (spec 3.3): P3's forceAtlas2, release and dispose, P5's fruchtermanReingold and
+ * springElectrical (the two other optional members of the real LayoutAccelerator, spec 9.3; the CPU option types in,
+ * the GPU simulations out), plus P7's seven algorithm members
  * (spec 8.2, 8.3; M8b-T8), non-optional here and returning the `Gpu*Result` shapes, which satisfy the `*ResultLike`
  * mirrors (spec 9.7: `precision` is an extra field, `F32` is a `NumericVector`). `connectedComponents` and
  * `weaklyConnectedComponents` are the same algorithm (spec 3.3: WCC semantics on directed input) under both names
@@ -100,6 +108,10 @@ export interface GpuAccelerator extends AlgorithmAccelerator, LayoutAccelerator
     readonly ctx: GpuContext;
     readonly options: Readonly<AcceleratorOptions>;
     forceAtlas2(options?: ForceAtlas2Options): GpuLayoutSimulation<ForceAtlas2Options, ForceAtlas2Stats>;
+    fruchtermanReingold(
+        options?: FruchtermanReingoldOptions,
+    ): GpuLayoutSimulation<FruchtermanReingoldOptions, FruchtermanReingoldStats>;
+    springElectrical(options?: SpringElectricalOptions): GpuLayoutSimulation<SpringElectricalOptions, SpringElectricalStats>;
     pageRank(s: GraphSnapshot, options?: PageRankOptions): Promise<GpuPageRankResult>;
     personalizedPageRank(
         s: GraphSnapshot,

package/src/types/layout.ts

@@ -43,6 +43,42 @@ export interface ForceAtlas2Stats extends LayoutStatsBase {
     readonly trace: ReadonlyArray<ForceAtlas2TraceRecord>;
 }
 
+/**
+ * One per-iteration trace record of the last completed batch of a Fruchterman-Reingold simulation (spec 3.3
+ * FruchtermanReingoldStats.trace element): K1 writes `temperature` from the iteration's uniform slot (spec 7.20).
+ * @public
+ */
+export interface FruchtermanReingoldTraceRecord {
+    readonly temperature: number;
+    readonly meanDisplacement: number;
+    readonly settledCount: number;
+}
+
+/** Spec 3.3 FruchtermanReingoldStats, verbatim: the cooling schedule's value replaces the controller fields. */
+export interface FruchtermanReingoldStats extends LayoutStatsBase {
+    readonly temperature: number;
+    readonly trace: ReadonlyArray<FruchtermanReingoldTraceRecord>;
+}
+
+/**
+ * One per-iteration trace record of the last completed batch of a spring-electrical simulation (spec 3.3
+ * SpringElectricalStats.trace element): `kineticEnergy` is `0.5 * sum m |v|^2` over the free nodes after the
+ * PREVIOUS iteration's integrate: K5 writes it into partials B and the NEXT iteration's K1 folds it (PD-4), so the
+ * first record after load() carries 0 and record i carries the energy of iteration i - 1.
+ * @public
+ */
+export interface SpringElectricalTraceRecord {
+    readonly kineticEnergy: number;
+    readonly meanDisplacement: number;
+    readonly settledCount: number;
+}
+
+/** Spec 3.3 SpringElectricalStats, verbatim; `kineticEnergy` is the last folded value, one iteration behind the last integrate (PD-4). */
+export interface SpringElectricalStats extends LayoutStatsBase {
+    readonly kineticEnergy: number;
+    readonly trace: ReadonlyArray<SpringElectricalTraceRecord>;
+}
+
 /** Options of GpuLayoutSimulation.run (spec 3.3). */
 export interface RunOptions {
     readonly maxIter?: number | undefined;

package/src/types/options.ts

@@ -6,7 +6,7 @@
  * import.
  */
 
-import type { F32, NodeId } from "@graphty/graph-format";
+import type { F32, NodeId, NodeMask } from "@graphty/graph-format";
 import type {
     CommonLayoutOptions,
     ForceAtlas2Options,
@@ -51,3 +51,47 @@ export interface ResolvedForceAtlas2Options {
     readonly iterationsPerStep: number;
     readonly maxInFlight: number;
 }
+
+/**
+ * The resolved (defaults applied) Fruchterman-Reingold option record (spec 7.20, 9.3): `k` null means `1 / sqrt(n)`
+ * at load; `fixed` is applied at load through ModelInputs.fixed (PD-6). Exported for src/layouts/fruchterman-reingold.ts
+ * and the option tests.
+ * @public
+ */
+export interface ResolvedFruchtermanReingoldOptions {
+    readonly k: number | null;
+    readonly iterations: number;
+    readonly cooling: "linear" | "adaptive";
+    readonly fixed: NodeMask | string | null;
+    readonly dim: 2 | 3;
+    readonly scale: number;
+    readonly center: readonly [number, number, number];
+    readonly seed: number | null;
+    readonly settleThreshold: number;
+    readonly settleWindow: number;
+    readonly iterationsPerStep: number;
+    readonly maxInFlight: number;
+}
+
+/**
+ * The resolved spring-electrical option record (spec 7.20, 9.3; ngraph's names): `gravity` is the Coulomb constant
+ * (negative repels), never FA2's centre gravity. `gravity` and `springCoefficient` are null when left to their
+ * defaults: ngraph's constant scaled by min(1, SE_SCALE_REFERENCE_NODES / n) once n is known at load. Exported for
+ * src/layouts/spring-electrical.ts and the option tests.
+ * @public
+ */
+export interface ResolvedSpringElectricalOptions {
+    readonly springLength: number;
+    readonly springCoefficient: number | null;
+    readonly gravity: number | null;
+    readonly dragCoefficient: number;
+    readonly timeStep: number;
+    readonly dim: 2 | 3;
+    readonly scale: number;
+    readonly center: readonly [number, number, number];
+    readonly seed: number | null;
+    readonly settleThreshold: number;
+    readonly settleWindow: number;
+    readonly iterationsPerStep: number;
+    readonly maxInFlight: number;
+}

package/src/wgsl/fa2-attraction.wgsl.ts

@@ -3,7 +3,10 @@
  * attraction force over the undirected CSR rows (both arcs present, so the sum is symmetric with no atomics), the
  * linear or linlog law, the optional weights, the distributed-action division by the mass in `pos.w`, written as
  * the FIRST writer of `force` each iteration. P3 ships the thread-per-row tier over `[tierStart, tierEnd)` = `[0, n)`
- * with `USE_PERM = false`; the subgroup / workgroup tiers arrive with P4 (`TIER`).
+ * with `USE_PERM = false`; the subgroup / workgroup tiers arrive with P4 (`TIER`). `LAW` (P5, spec 7.20) picks the
+ * pair law: 0 = the FA2 text, 1 = Fruchterman-Reingold `d^2 / k` (unfloored), 2 = ngraph's Hooke spring
+ * `k_s (d - L)`; under 1 / 2 the models compile `LINLOG = false` and `HAS_WEIGHTS = false`, and the law overwrites
+ * `w` so weights are ignored either way.
  *
  * Body only (spec 3.5, D9); normative text (contract 4.5); the K2 sabotage mutations (P3-T5) are textual edits of it.
  */
@@ -29,6 +32,8 @@ fn attraction(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_i
         if (HAS_WEIGHTS) { w = weights[a]; }
         let d = pos[j].xyz - pi.xyz;                           // toward j
         let len = max(length(d), FA2_DIST_FLOOR);
+        if (LAW == 1u) { w = length(d) / P.frK; }              // LAW 1 (FR, 7.20): |F| = d^2 / k along d / d, unfloored; the linear select below applies w as is
+        if (LAW == 2u) { w = P.springCoefficient * (len - P.springLength) / len; }   // LAW 2 (spring, ngraph generateCreateSpringForce.js:33-36): Hooke k_s (d - L) toward j
         let mag = select(w, w * log(1.0 + len) / len, LINLOG); // linear: |F| = w len; linlog: |F| = w log(1 + len)
         f = f + d * mag;
     }

package/src/wgsl/fa2-integrate.wgsl.ts

@@ -4,7 +4,12 @@
  * networkx mode `m |F|`, contract 4.6), the position update with no displacement clamp (D25), z never integrated
  * in 2D (spec 7.13), `oldForce` stored in paper mode for fixed nodes too (spec 7.11), and the partials A
  * (sum p, sum |p - c|^2, min, max with max |p - c|^2 in `max.w`) and C (sum |dp| over free rows, free count) in
- * uniform control flow.
+ * uniform control flow. `APPLY` (P5, spec 7.20) picks the integrator: 0 = the FA2 text, 1 = the Fruchterman-Reingold
+ * temperature cap `min(|F|, t)` along F, 2 = ngraph's semi-implicit Euler step with drag and the unit speed clamp
+ * over the velocity that lives in the `oldForce` slot (PD-2), which also folds the free kinetic energy into
+ * `partials.swingTraction.x` (PD-4); mode 1 folds the free force energy `sum |F|^2` into the same slot for K1's
+ * adaptive cooling and takes its temperature from the state block when `FA2_FLAG_ADAPTIVE` is set. The energy
+ * reduction runs under every mode; only its write is conditional.
  *
  * Body only (spec 3.5, D9); normative text (contract 4.5); the K5 sabotage mutations (P3-T5) are textual edits of it.
  */
@@ -25,6 +30,7 @@ fn integrate(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id
     var p = vec4f(0.0);
     var free = false;
     var valid = false;
+    var ke = 0.0;
     if (i < P.n) {
         valid = true;
         let f = load_force(i);
@@ -33,7 +39,25 @@ fn integrate(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id
         if (SWING_MODE == 0u) { swing_i = p.w * length(f - load_old(i)); }  // paper: m |F(t) - F(t-1)|, recomputed inline (7.2)
         let factor = S.speed / (1.0 + sqrt(S.speed * swing_i));
         let fixed = mask_bit(fixedMask[i >> 5u], i);
-        dp = select(f * factor, vec3f(0.0), fixed);                        // no clamp on dp (D25)
+        dp = select(f * factor, vec3f(0.0), fixed);                        // APPLY 0 (FA2): no clamp on dp (D25)
+        if (APPLY == 1u) {                                                  // APPLY 1 (FR, 7.20): move along F by min(|F|, t); a fixed node stays
+            let mag = length(f);
+            let t = select(P.temperature, S.temperature, (P.flags & FA2_FLAG_ADAPTIVE) != 0u);   // adaptive cooling: K1's state temperature
+            dp = vec3f(0.0);
+            if (mag > 0.0 && !fixed) { dp = f * (min(mag, t) / mag); }
+            ke = select(0.0, dot(f, f), !fixed);                              // the force energy of Hu's step control, folded like the spring preset's kinetic energy
+        }
+        if (APPLY == 2u) {                                                  // APPLY 2 (spring-electrical): ngraph's Euler step over the velocity in the oldForce slot (PD-2)
+            var v = load_old(i);
+            let fd = f - P.dragCoefficient * v;                             // drag (generateCreateDragForce.js:18)
+            v = v + (P.timeStep / p.w) * fd;                                 // v += (dt / m) F (generateIntegrator.js:27-29)
+            let sp = length(v);
+            if (sp > 1.0) { v = v / sp; }                                     // the unit speed clamp (generateIntegrator.js:33-37)
+            if (P.dim == 2u) { v.z = 0.0; }
+            dp = select(P.timeStep * v, vec3f(0.0), fixed);                  // dp = dt v; a pinned body is skipped (generateIntegrator.js:21, 39-41)
+            if (!fixed) { store_old(i, v); }
+            ke = select(0.0, 0.5 * p.w * dot(v, v), !fixed);                 // partials B under APPLY 2 (PD-4)
+        }
         if (P.dim == 2u) { dp.z = 0.0; }                                   // 2D never integrates z (7.13)
         p = vec4f(p.xyz + dp, p.w);
         pos[i] = p;
@@ -59,11 +83,13 @@ fn integrate(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id
     let tHi = wg_reduce_vec4(hi, lid.x, 2u);
     let tDl = wg_reduce_f32(dl, lid.x, 0u);
     let tFr = wg_reduce_u32(fr, lid.x, 0u);
+    let tKe = wg_reduce_f32(ke, lid.x, 0u);
     if (lid.x == 0u) {
         let g = group_id(wid);
         partials[g].sum = tSum;
         partials[g].min = tLo;
         partials[g].max = tHi;
         partials[g].dispFree = vec2f(tDl, f32(tFr));
+        if (APPLY != 0u) { partials[g].swingTraction = vec2f(tKe, 0.0); }   // overwrites K3's epilogue: K4 never runs under FR or the preset (PD-4)
     }
 }`;

package/src/wgsl/fa2-repulsion-exact.wgsl.ts

@@ -1,6 +1,8 @@
 /**
  * The `fa2-repulsion-exact` kernel body (K3; contract 4.5; spec 7.6, 7.9, 7.10): the tiled all-pairs repulsion
- * `|F| = k m_i m_j / d` with the 0.01 distance floor and the antisymmetric coincident kick, the gravity epilogue
+ * `|F| = k m_i m_j / d` with the 0.01 distance floor and the antisymmetric coincident kick (`LAW` 0; P5's `LAW` 1
+ * is Fruchterman-Reingold `k^2 / d` and `LAW` 2 ngraph's Coulomb `-g m_i m_j / d^2`, both unfloored, spec 7.20,
+ * with the kick's magnitude taken from the law at d = 0.01, PD-10), the gravity epilogue
  * (GRAVITY_CENTER 0 = centroid, 1 = origin; STRONG_GRAVITY) added under the `valid` guard, `force += f`, and the
  * swing / traction workgroup reduction in uniform control flow (SWING_MODE 0 = paper: free nodes only against
  * `oldForce`; 1 = NetworkX: positions and forces mixed, every node) whose lane 0 writes
@@ -18,6 +20,11 @@ fn store_force(i: u32, f: vec3f) {
     force[3u * i + 2u] = f.z;
 }
 fn load_old(i: u32) -> vec3f { return vec3f(oldForce[3u * i], oldForce[3u * i + 1u], oldForce[3u * i + 2u]); }
+fn kick_magnitude(mi: f32, mj: f32) -> f32 {                   // the law's magnitude at d = FA2_DIST_FLOOR (PD-10)
+    if (LAW == 1u) { return P.frK * P.frK / FA2_DIST_FLOOR; }
+    if (LAW == 2u) { return -P.coulomb * mi * mj / FA2_DIST_FLOOR_SQ; }
+    return P.scalingRatio * mi * mj / FA2_DIST_FLOOR;
+}
 fn gravity_force(pi: vec4f) -> vec3f {                         // spec 7.9: centroid (GRAVITY_CENTER 0) or origin (1); regular or strong
     var q = pi.xyz;
     if (GRAVITY_CENTER == 0u) { q = pi.xyz - S.centroid.xyz; }
@@ -45,13 +52,15 @@ fn repulsion(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id
             if (o.w > 0.0 && jj != i) {                                           // mass > 0 for every real node, 0 for the pad
                 let d = pi.xyz - o.xyz;
                 var d2 = dot(d, d);
-                if (d2 < FA2_COINCIDENT_SQ) {                                     // coincident: antisymmetric unit kick of magnitude k m_i m_j / 0.01 (7.2)
-                    f = f + kick_dir(i, jj, P.dim) * (P.scalingRatio * pi.w * o.w / FA2_DIST_FLOOR);
+                if (d2 < FA2_COINCIDENT_SQ) {                                     // coincident: antisymmetric unit kick of the law's magnitude at d = 0.01 (7.2; PD-10)
+                    f = f + kick_dir(i, jj, P.dim) * kick_magnitude(pi.w, o.w);
                     continue;
                 }
-                d2 = max(d2, FA2_DIST_FLOOR_SQ);                                  // d >= 0.01
+                if (LAW == 0u) { d2 = max(d2, FA2_DIST_FLOOR_SQ); }               // FA2 alone floors d >= 0.01 (7.2); FR and coulomb are unfloored (7.20)
                 let k = P.scalingRatio * pi.w * o.w;
-                f = f + d * (k / d2);                                             // |F| = k m_i m_j / d along d / d
+                if (LAW == 0u) { f = f + d * (k / d2); }                          // LAW 0 (FA2): |F| = k m_i m_j / d along d / d
+                if (LAW == 1u) { f = f + d * (P.frK * P.frK / d2); }              // LAW 1 (FR, 7.20): |F| = k^2 / d, mass ignored
+                if (LAW == 2u) { f = f + d * (-P.coulomb * pi.w * o.w / (d2 * sqrt(d2))); }   // LAW 2 (coulomb, ngraph generateQuadTree.js:131-132): |F| = -g m_i m_j / d^2
             }
         }
         workgroupBarrier();

package/src/wgsl/fa2-stats-finalize.wgsl.ts

@@ -4,6 +4,13 @@
  * exact spec 3.3 value from `partials.max.w`), bounding box, mean displacement over free nodes (0 when every node
  * is fixed), the settle counter -- increments the iteration counter and writes the K1 half of the trace record.
  * On the first iteration after load() (`FA2_FLAG_FIRST`) it folds nothing and keeps the host-written state.
+ * `STATS_MODE` (P5, spec 7.20) adds the model statistic: 0 = the FA2 text, 1 = the Fruchterman-Reingold temperature
+ * of this iteration into `S.temperature` and the trace's `modelScalar` -- the uniform's under the linear schedule,
+ * or, with `FA2_FLAG_ADAPTIVE` set, the adaptive one: the previous iteration's force energy (K5 folds sum |F|^2 over
+ * free nodes into `partials.swingTraction.x`) against `S.frEnergy` grows the temperature by 1 / FR_COOLING_STEP after
+ * FR_COOLING_PATIENCE consecutive falls and shrinks it by FR_COOLING_STEP on a rise (Yifan Hu 2005, section 3.2);
+ * 2 = the spring-electrical kinetic energy K5 folded into `partials.swingTraction.x` (PD-4) into `S.kineticEnergy`
+ * and the trace.
  *
  * This file holds the kernel BODY only (spec 3.5, D9): no bind-group lines and no `override` lines -- the composer
  * emits them from the registry entry in src/kernels.ts (contract 3.10.1). The text is normative (contract 4.5) and
@@ -21,6 +28,7 @@ fn stats_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
     var hi = vec4f(-F32_MAX);
     var disp = 0.0;
     var free = 0u;
+    var ke = 0.0;
     if (fold) {
         for (var g = lid.x; g < groups; g = g + WG) {   // sequential per lane in index order: deterministic
             let q = partials[g];
@@ -29,6 +37,7 @@ fn stats_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
             hi = max(hi, q.max);
             disp = disp + q.dispFree.x;
             free = free + u32(q.dispFree.y);
+            ke = ke + q.swingTraction.x;
         }
     }
     let tSum = wg_reduce_vec4(sum, lid.x, 0u);
@@ -36,6 +45,7 @@ fn stats_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
     let tHi = wg_reduce_vec4(hi, lid.x, 2u);
     let tDisp = wg_reduce_f32(disp, lid.x, 0u);
     let tFree = wg_reduce_u32(free, lid.x, 0u);
+    let tKe = wg_reduce_f32(ke, lid.x, 0u);
     if (lid.x == 0u) {
         if (fold) {
             let n = f32(P.n);
@@ -53,5 +63,28 @@ fn stats_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
         T[P.iterationIndex].meanDisplacement = S.meanDisplacement;
         T[P.iterationIndex].settledCount = S.settledCount;
         T[P.iterationIndex].iteration = S.iteration;
+        if (STATS_MODE == 1u) {                                    // FR: this iteration's temperature (7.20) into the state and the trace
+            if ((P.flags & FA2_FLAG_ADAPTIVE) != 0u) {                // adaptive cooling (Yifan Hu 2005 3.2): tKe is the previous iteration's sum |F|^2 over free nodes
+                if (fold) {
+                    var t = S.temperature;
+                    if (tKe < S.frEnergy) {
+                        S.frProgress = S.frProgress + 1u;
+                        if (S.frProgress >= FR_COOLING_PATIENCE) { S.frProgress = 0u; t = t / FR_COOLING_STEP; }
+                    } else {
+                        S.frProgress = 0u;
+                        t = t * FR_COOLING_STEP;
+                    }
+                    S.frEnergy = tKe;
+                    S.temperature = t;
+                }
+            } else {
+                S.temperature = P.temperature;
+            }
+            T[P.iterationIndex].modelScalar = S.temperature;
+        }
+        if (STATS_MODE == 2u) {                                    // spring-electrical: the kinetic energy K5 folded into partials B (PD-4); 0 on the first iteration after load()
+            S.kineticEnergy = tKe;
+            T[P.iterationIndex].modelScalar = tKe;
+        }
     }
 }`;