@graphty/webgpu-graph-algorithms 0.5.0 → 0.6.0

package/dist/chunks/{context-CRbw2Wyo.js → context-BXqgCifx.js}

@@ -3,6 +3,7 @@ const WORKGROUP_SIZE = 256;
 const MAX_WORKGROUPS_PER_DIM = 65535;
 const MAX_1D_ITEMS = MAX_WORKGROUPS_PER_DIM * WORKGROUP_SIZE;
 const U32_MAX = 4294967295;
+const RADIX_BINS = 256;
 const ARC_WINDOW_ALIGN = 64;
 const STORAGE_ALIGN = 256;
 const UNIFORM_SLOT_BYTES = 256;
@@ -49,6 +50,44 @@ const FA2_DISTANCE_FLOOR = 0.01;
 const FA2_DISTANCE_FLOOR_SQ = 1e-4;
 const FA2_COINCIDENT_SQ = 1e-8;
 const FA2_FLAG_FIRST = 1;
+const FA2_FLAG_ADAPTIVE = 2;
+const FR_START_TEMPERATURE = 0.1;
+const FR_REHEAT_FRACTION = 0.7;
+const FR_COOLING_STEP = 0.9;
+const FR_COOLING_PATIENCE = 5;
+const FR_ADAPTIVE_MAX_ITERATIONS = 1e4;
+const FR_DEFAULTS = Object.freeze({
+  k: null,
+  iterations: 50,
+  fixed: null,
+  dim: 2,
+  scale: 1,
+  settleThreshold: 1e-3,
+  settleWindow: 10,
+  iterationsPerStep: 1,
+  maxInFlight: 2,
+  cooling: "linear"
+});
+const SE_SCALE_REFERENCE_NODES = 300;
+const SE_DEFAULTS = Object.freeze({
+  springLength: 10,
+  springCoefficient: 0.8,
+  gravity: -12,
+  dragCoefficient: 0.9,
+  timeStep: 0.5,
+  dim: 2,
+  scale: 1,
+  settleThreshold: 1e-3,
+  settleWindow: 10,
+  iterationsPerStep: 1,
+  maxInFlight: 2
+});
+const GRID_MIN_SIDE = 8;
+const GRID_COARSEST_SIDE = 4;
+const GRID_HUB_CELL = 1024;
+const GRID_EXTENT_FLOOR = 1e-6;
+const GRID_BBOX_MARGIN = 1.01;
+const GRID_SORT_BITS = 24;
 const PASSTHROUGH_FORMAT_CODES = Object.freeze(["E_GPU_INELIGIBLE", "E_UNKNOWN_NODE", "E_UNKNOWN_COLUMN", "E_COLUMN_LENGTH"]);
 const EMPTY_DETAILS = Object.freeze({});
 class WebGpuGraphError extends Error {
@@ -511,6 +550,7 @@ function deviceLostError(info) {
     message: info.message
   });
 }
+const INDIRECT_ARGS_STRIDE = 16;
 const bufferIds = /* @__PURE__ */ new WeakMap();
 let nextBufferId = 1;
 function bufferId(buffer) {
@@ -701,6 +741,42 @@ class Kernel {
    * @param dynamicOffsets - one byte offset per entry of bound.dynamicGroups
    */
   dispatch(pass, bound, plan, dynamicOffsets) {
+    this.check(bound, dynamicOffsets);
+    if (plan.x === 0) {
+      return;
+    }
+    this.setUp(pass, bound, dynamicOffsets);
+    pass.dispatchWorkgroups(plan.x, plan.y, 1);
+  }
+  /**
+   * setPipeline + the bind groups exactly as dispatch(), then dispatchWorkgroupsIndirect(args.buffer, args.offset +
+   * INDIRECT_ARGS_STRIDE * slot) (spec 5.4): the (x, y, 1) of the slot were written by the indirect-finalize kernel
+   * earlier in the same pass. A slot beyond the binding is E_INVALID_ARGUMENT.
+   * @param pass - the open compute pass
+   * @param bound - a BoundKernel of THIS kernel
+   * @param args - the args buffer range (usage INDIRECT | STORAGE)
+   * @param slot - the 16-byte slot index inside the range
+   * @param dynamicOffsets - one byte offset per entry of bound.dynamicGroups
+   */
+  dispatchIndirect(pass, bound, args, slot, dynamicOffsets) {
+    this.check(bound, dynamicOffsets);
+    if (!Number.isInteger(slot) || slot < 0 || (slot + 1) * INDIRECT_ARGS_STRIDE > args.size) {
+      throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${this.spec.id}: args slot ${slot} is outside the binding`, {
+        argument: "slot",
+        value: slot,
+        expected: `0 <= slot < ${Math.floor(args.size / INDIRECT_ARGS_STRIDE)}`
+      });
+    }
+    this.setUp(pass, bound, dynamicOffsets);
+    pass.dispatchWorkgroupsIndirect(args.buffer, args.offset + INDIRECT_ARGS_STRIDE * slot);
+  }
+  /**
+   * The argument checks dispatch() and dispatchIndirect() share: a BoundKernel of another kernel or an offset list
+   * of the wrong length is E_INVALID_ARGUMENT.
+   * @param bound - the bound kernel
+   * @param dynamicOffsets - the offsets, if any
+   */
+  check(bound, dynamicOffsets) {
     const { id } = this.spec;
     if (bound.kernel !== this) {
       throw new WebGpuGraphError(
@@ -724,9 +800,15 @@ class Kernel {
         }
       );
     }
-    if (plan.x === 0) {
-      return;
-    }
+  }
+  /**
+   * setPipeline + setBindGroup for every group (the dynamic offsets replicated over the uniform bindings of each
+   * dynamic group), the prefix dispatch() and dispatchIndirect() share.
+   * @param pass - the open compute pass
+   * @param bound - a BoundKernel of this kernel
+   * @param dynamicOffsets - one byte offset per entry of bound.dynamicGroups (absent = 0)
+   */
+  setUp(pass, bound, dynamicOffsets) {
     pass.setPipeline(this.pipeline);
     let next = 0;
     bound.bindGroups.forEach((bindGroup, group) => {
@@ -743,7 +825,6 @@ class Kernel {
         pass.setBindGroup(group, bindGroup);
       }
     });
-    pass.dispatchWorkgroups(plan.x, plan.y, 1);
   }
   /** Drops cached bind groups (a layout's buffers changed). */
   invalidate() {
@@ -807,6 +888,14 @@ const FA2_DIST_FLOOR: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR)};
 const FA2_DIST_FLOOR_SQ: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR_SQ)};
 const FA2_COINCIDENT_SQ: f32 = ${wgslF32Literal(FA2_COINCIDENT_SQ)};
 const FA2_FLAG_FIRST: u32 = ${FA2_FLAG_FIRST}u;
+const FA2_FLAG_ADAPTIVE: u32 = ${FA2_FLAG_ADAPTIVE}u;
+const FR_COOLING_STEP: f32 = ${wgslF32Literal(FR_COOLING_STEP)};
+const FR_COOLING_PATIENCE: u32 = ${FR_COOLING_PATIENCE}u;
+const GRID_HUB_CELL: u32 = ${GRID_HUB_CELL}u;
+const GRID_EXTENT_FLOOR: f32 = ${wgslF32Literal(GRID_EXTENT_FLOOR)};
+const GRID_BBOX_MARGIN: f32 = ${wgslF32Literal(GRID_BBOX_MARGIN)};
+const RADIX_BINS: u32 = ${RADIX_BINS}u;
+const RADIX_DIGIT_MASK: u32 = ${RADIX_BINS - 1}u;
 const F32_MAX: f32 = 0x1.fffffep+127;
 override WG: u32 = ${WORKGROUP_SIZE}u;
 override USE_PERM: bool = false;
@@ -1475,8 +1564,10 @@ class Profiler {
    */
   constructor(device, enabled, quantised, slots) {
     this.labels = /* @__PURE__ */ new WeakMap();
+    this.partialRequests = /* @__PURE__ */ new WeakSet();
     this.pending = [];
     this.cursor = 0;
+    this.refused = 0;
     this.destroyed = false;
     const count = slots ?? PROFILER_QUERY_SLOTS;
     this.quantised = quantised;
@@ -1496,12 +1587,17 @@ class Profiler {
     }
   }
   /**
-   * The timestampWrites descriptor for a new pass, or undefined when disabled / out of slots.
+   * The timestampWrites descriptor for a new pass, or undefined when disabled / out of slots. A pass refused for
+   * want of slots is counted, and the next `resolveInto()` marks its request partial.
    * @param label - the pass name reported by `timings()`
    * @returns the descriptor a CommandBatch puts on beginComputePass, or undefined
    */
   beginPass(label) {
-    if (this.querySet === null || this.destroyed || this.cursor + 2 > this.slots) {
+    if (this.querySet === null || this.destroyed) {
+      return void 0;
+    }
+    if (this.cursor + 2 > this.slots) {
+      this.refused++;
       return void 0;
     }
     const begin = this.cursor;
@@ -1526,10 +1622,23 @@ class Profiler {
       request,
       this.pending.map((pass) => pass.label)
     );
+    if (this.refused > 0) {
+      this.partialRequests.add(request);
+    }
     this.pending = [];
     this.cursor = 0;
+    this.refused = 0;
     return request;
   }
+  /**
+   * Whether a pass of the batch was refused a slot pair, so `timings()` covers only its first slots / 2 passes
+   * and their sum is not the batch's duration.
+   * @param request - the request `resolveInto()` returned
+   * @returns true when at least one pass of that batch went untimed
+   */
+  partial(request) {
+    return this.partialRequests.has(request);
+  }
   /**
    * Decodes the timings of a batch from its readback bytes.
    * @param bytes - the resolved readback of the batch
@@ -1562,6 +1671,7 @@ class Profiler {
     this.destroyed = true;
     this.pending = [];
     this.cursor = 0;
+    this.refused = 0;
     if (this.querySet !== null) {
       this.querySet.destroy();
     }
@@ -2130,7 +2240,7 @@ class Readback {
   }
 }
 const CORE_ORDER$1 = Object.freeze(["rowPtr", "colIdx", "weights", "arcToEdge", "edgeToArc"]);
-const ARC_INDEXED = /* @__PURE__ */ new Set(["colIdx", "weights", "arcToEdge"]);
+const ARC_INDEXED$1 = /* @__PURE__ */ new Set(["colIdx", "weights", "arcToEdge"]);
 function coreByteLengths(s) {
   const arcs = s.arcCount;
   const identity = s.flags.arcToEdgeIsIdentity;
@@ -2304,13 +2414,17 @@ function planUpload(s, caps, need) {
   const windows = planArcWindows(s.rowPtr, s.arcCount, arcsPerWindow);
   const { buffers, placed } = placeWindows(windows, 4 * s.arcCount, bufferLimit);
   const arrays = names.map(
-    (name) => ARC_INDEXED.has(name) ? { name, byteLength: lengths[name], buffers } : { name, byteLength: lengths[name], buffers: [{ byteOffset: 0, byteLength: lengths[name] }] }
+    (name) => ARC_INDEXED$1.has(name) ? { name, byteLength: lengths[name], buffers } : { name, byteLength: lengths[name], buffers: [{ byteOffset: 0, byteLength: lengths[name] }] }
   );
   return { kind: "windowed", arrays, windows: placed, arcsPerWindow };
 }
 const DEFAULT_NEED = Object.freeze(["rowPtr", "colIdx", "weights"]);
 const CORE_ORDER = Object.freeze(["rowPtr", "colIdx", "weights", "arcToEdge", "edgeToArc"]);
+const ARC_INDEXED = Object.freeze(["colIdx", "weights", "arcToEdge"]);
 const RESIDENT_USAGE = BufferUsage.STORAGE | BufferUsage.COPY_DST | BufferUsage.COPY_SRC;
+function isArcIndexed(name) {
+  return ARC_INDEXED.includes(name);
+}
 function isSharedBuffer(buffer) {
   return Object.prototype.toString.call(buffer) === "[object SharedArrayBuffer]";
 }
@@ -2396,8 +2510,9 @@ class GraphResidency {
   }
   /**
    * Uploads (or finds) the core; `need` defaults to ["rowPtr", "colIdx", "weights"]; cold segments on demand
-   * (spec 4.2). Never materialises an identity permutation. A windowed plan throws E_TOO_LARGE { path: "windowed" }
-   * until P4 (PLAN DECISION 2); a tombstoned serial is lifted and re-uploaded (PLAN DECISION 7).
+   * (spec 4.2). Never materialises an identity permutation. A windowed plan (spec 4.2, PD-8) uploads every
+   * arc-indexed array as the plan's buffer ranges and binds window 0 as its default binding; rowPtr and edgeToArc
+   * stay whole. A tombstoned serial is lifted and re-uploaded (PLAN DECISION 7).
    * @param s - the snapshot
    * @param need - the core arrays to bind (rowPtr is always included; absent arrays are ignored)
    * @returns the core binding (a frozen object; grows as cold segments are added)
@@ -2408,18 +2523,6 @@ class GraphResidency {
     const wanted = need ?? DEFAULT_NEED;
     const names = CORE_ORDER.filter((name) => (name === "rowPtr" || wanted.includes(name)) && isPresent(s, name));
     const plan = planUpload(s, this.caps, names);
-    if (plan.kind === "windowed") {
-      throw new WebGpuGraphError(
-        "E_TOO_LARGE",
-        `snapshot ${s.serial}: an arc array of ${4 * s.arcCount} bytes needs arc windows (${plan.windows.length}), which P1-P3 plan but do not execute`,
-        {
-          needed: 4 * s.arcCount,
-          limit: this.caps.limits.maxStorageBufferBindingSize,
-          path: "windowed",
-          algorithm: null
-        }
-      );
-    }
     const record = this.ensureRecord(s);
     if (record.plan === null) {
       record.plan = plan.kind;
@@ -2433,10 +2536,17 @@ class GraphResidency {
         );
         record.arena = { buffer: resident.buffer, segments: plan.segments };
       }
+      if (plan.kind === "windowed") {
+        record.windows = plan.windows;
+      }
     }
     for (const name of names) {
       if (!record.bindings.has(name)) {
-        record.bindings.set(name, this.bindCore(record, s, name));
+        const planned = plan.kind === "windowed" ? plan.arrays.find((a) => a.name === name) : void 0;
+        record.bindings.set(
+          name,
+          planned !== void 0 && planned.buffers.length > 0 && record.windows !== null && isArcIndexed(name) ? this.bindWindowed(record, s, name, planned.buffers, record.windows[0]) : this.bindCore(record, s, name)
+        );
       }
     }
     const rowPtr = record.bindings.get("rowPtr");
@@ -2452,7 +2562,12 @@ class GraphResidency {
       weights,
       arcToEdge: record.bindings.get("arcToEdge") ?? null,
       edgeToArc: record.bindings.get("edgeToArc") ?? null,
-      windows: null,
+      windows: record.windows,
+      arcBuffers: record.windows === null ? null : Object.freeze({
+        colIdx: Object.freeze([...record.arcBuffers.get("colIdx") ?? []]),
+        weights: Object.freeze([...record.arcBuffers.get("weights") ?? []]),
+        arcToEdge: Object.freeze([...record.arcBuffers.get("arcToEdge") ?? []])
+      }),
       hasWeights: weights !== null
     });
   }
@@ -2558,6 +2673,18 @@ class GraphResidency {
     const rev = s.reverse();
     if (!s.directed) {
       const core = this.core(s, ["rowPtr", "colIdx", "weights"]);
+      if (core.plan === "windowed") {
+        throw new WebGpuGraphError(
+          "E_TOO_LARGE",
+          `snapshot ${s.serial}: the undirected reverse view is the core, which needs arc windows (${core.windows?.length ?? 0}) that no view executes`,
+          {
+            needed: 4 * s.arcCount,
+            limit: this.caps.limits.maxStorageBufferBindingSize,
+            path: "windowed",
+            algorithm: null
+          }
+        );
+      }
       const bindings2 = { rowPtr: core.rowPtr };
       if (core.colIdx !== null) {
         bindings2.colIdx = core.colIdx;
@@ -2857,6 +2984,50 @@ class GraphResidency {
     const resident = this.upload(record, array, array, `residency:core:${record.serial}:${name}`);
     return { buffer: resident.buffer, offset: 0, size: resident.byteLength, window: null };
   }
+  /**
+   * Uploads one arc-indexed array as the windowed plan's buffer ranges (spec 4.2: an array above maxBufferSize is
+   * split across buffers at window boundaries), each keyed on a marker object of the record (windowKey), and
+   * returns window 0's binding so a caller that ignores windows still binds something valid (PD-8).
+   * @param record - the snapshot's record
+   * @param s - the snapshot
+   * @param name - a PRESENT arc-indexed core array
+   * @param ranges - the plan's buffer ranges of the array
+   * @param first - window 0
+   * @returns the binding of window 0
+   */
+  bindWindowed(record, s, name, ranges, first) {
+    const array = coreArray(s, name);
+    const buffers = ranges.map(
+      (range, index) => this.upload(
+        record,
+        this.windowKey(record, `${name}:${index}`),
+        new Uint8Array(array.buffer, array.byteOffset + range.byteOffset, range.byteLength),
+        `residency:core:${record.serial}:${name}:w${index}`
+      ).buffer
+    );
+    record.arcBuffers.set(name, buffers);
+    return {
+      buffer: buffers[first.bufferIndex],
+      offset: first.offset,
+      size: 4 * (first.end - first.start),
+      window: first
+    };
+  }
+  /**
+   * The upload key of one window buffer: a marker object allocated once per record and `<name>:<bufferIndex>`.
+   * @param record - the owning record
+   * @param memoKey - `<name>:<bufferIndex>`
+   * @returns the stable marker object
+   */
+  windowKey(record, memoKey) {
+    const existing = record.windowKeys.get(memoKey);
+    if (existing !== void 0) {
+      return existing;
+    }
+    const created = {};
+    record.windowKeys.set(memoKey, created);
+    return created;
+  }
   /**
    * Uploads `data` into a new buffer keyed on `key`, or returns the resident already uploaded for that key by
    * the same owner (PLAN DECISION 11: a resident belongs to one record).
@@ -2920,6 +3091,9 @@ class GraphResidency {
     record.bindings.clear();
     record.views.clear();
     record.packKeys.clear();
+    record.windowKeys.clear();
+    record.arcBuffers.clear();
+    record.windows = null;
     record.arena = null;
     record.plan = null;
     this.bySerial.delete(record.serial);
@@ -2947,6 +3121,9 @@ class GraphResidency {
         bindings: /* @__PURE__ */ new Map(),
         views: /* @__PURE__ */ new Map(),
         packKeys: /* @__PURE__ */ new Map(),
+        windowKeys: /* @__PURE__ */ new Map(),
+        windows: null,
+        arcBuffers: /* @__PURE__ */ new Map(),
         released: false
       };
       this.bySerial.set(s.serial, record);
@@ -3272,24 +3449,39 @@ export {
   EXACT_MAX_NODES as E,
   FA2_DEFAULTS as F,
   GpuContext as G,
+  INDIRECT_ARGS_STRIDE as I,
   LAYOUT_TUNING_DEFAULTS as L,
   MAX_WORKGROUPS_PER_DIM as M,
   PARTIAL_BYTES as P,
+  RADIX_BINS as R,
   STATE_HEADER_BYTES as S,
   TRACE_RECORD_BYTES as T,
   UNIFORM_SLOT_BYTES as U,
   WebGpuGraphError as W,
   WGSL_RESERVED_WORDS as a,
   U32_MAX as b,
-  MAX_ITERATIONS_PER_STEP as c,
+  GRID_COARSEST_SIDE as c,
   deviceLostError as d,
-  MAX_1D_ITEMS as e,
-  FA2_FLAG_FIRST as f,
-  PASSTHROUGH_FORMAT_CODES as g,
-  hasErrorCode as h,
+  GRID_MIN_SIDE as e,
+  GRID_SORT_BITS as f,
+  MAX_ITERATIONS_PER_STEP as g,
+  MAX_1D_ITEMS as h,
   isWebGpuGraphError as i,
-  STORAGE_ALIGN as j,
-  WORKGROUP_SIZE as k,
-  isSoftwareAdapter as l
+  hasErrorCode as j,
+  FA2_FLAG_FIRST as k,
+  GRID_HUB_CELL as l,
+  GRID_BBOX_MARGIN as m,
+  GRID_EXTENT_FLOOR as n,
+  FR_ADAPTIVE_MAX_ITERATIONS as o,
+  FR_START_TEMPERATURE as p,
+  FA2_FLAG_ADAPTIVE as q,
+  FR_REHEAT_FRACTION as r,
+  FR_DEFAULTS as s,
+  SE_DEFAULTS as t,
+  SE_SCALE_REFERENCE_NODES as u,
+  PASSTHROUGH_FORMAT_CODES as v,
+  STORAGE_ALIGN as w,
+  WORKGROUP_SIZE as x,
+  isSoftwareAdapter as y
 };
-//# sourceMappingURL=context-CRbw2Wyo.js.map
+//# sourceMappingURL=context-BXqgCifx.js.map