@graphty/webgpu-graph-algorithms 0.6.26 → 0.6.28

package/dist/src/algorithms/closeness.d.ts

@@ -1,42 +1,42 @@
 /**
- * Closeness centrality on the device (design 8.4, 3.3 line 810, 9.7; P8-T11, the P8 plan's PD-13 / PD-19 / PD-25 /
- * DEP-P8-E / DEP-P8-F): `score[s] = 1 / sumDist_s`, with `sumDist_s` the exact sum of the finite distances from `s`
- * to every OTHER node -- an unreached node adds nothing -- and `0` when nothing is reached. No reached factor and no
- * Wasserman-Faust scaling: this is EXACTLY the legacy default (`normalized: false`) of `closenessCentrality` in
- * `@graphty/algorithms`, the number graphty-element's closeness panel shows today, so a future `indexed` port has one
- * number to match (the NetworkX form is 33x it on karate and could never have been substituted silently).
+ * Closeness centrality on the device (design 8.4, 3.3 line 810, 9.7): `score[s] = 1 / sumDist_s`, with `sumDist_s`
+ * the exact sum of the finite distances from `s` to every OTHER node -- an unreached node adds nothing -- and `0` when
+ * nothing is reached; or, with `harmonic`, `score[s] = sum of 1 / dist` over the same nodes (a zero distance adds
+ * nothing). No reached factor and no Wasserman-Faust scaling: this is EXACTLY the legacy default (`normalized:
+ * false`) of `closenessCentrality` in `@graphty/algorithms`, the number graphty-element's closeness panel shows.
  *
- * The unweighted route is ONE bit-parallel multi-source search per batch of 32 sources (`ceil(n / 32)` batches):
- * the batch's state is one `bits` buffer of four regions of `bitsBase = roundUp(n, 64)` words (`visited`, two
- * frontier regions that swap by the level's parity, `flags`), bit `s` of word `v` meaning "source `s` has reached /
- * is at / is next at `v`"; a level is, all host-recorded, `closeness-reduce` role 0 (the boundary: `done` from the
- * previous level's compacted count, the level's claims folded into the exact 64-bit per-source sums at `level + 1`),
- * `compact` of the flags into the frontier list, two `fill`s zeroing the level's next region and the flags (AFTER
- * the compaction that consumed them), and `closeness-sweep` (the block-mapped expansion with the claim inline, a
- * direct grid-stride dispatch looping to the list's count). `MAX_LEVELS_PER_SUBMIT` levels per submit and
- * one readback per submit (the `done` word and the 512-byte `perSource` block together, so the finished batch needs
- * no extra map); the host folds `sumHi x 2^32 + sumLo` into `1 / sum` in f64 and stores f32. The weighted route
- * (`weighted` true on a snapshot whose column is not all ones) is one `sssp` per source with the sums reduced on the
- * host between calls: design 8.4's own answer, slow and correct. `weighted` defaults to the snapshot's `flags.weighted`;
- * `weighted: false` on a weighted snapshot ignores the column by request and sweeps; `weighted: true` over unit
- * weights or no column sweeps too (every `sssp` would route to a BFS anyway). `maxIterations` and `tolerance` are the
+ * Three routes, chosen from the inputs before any device work:
+ *
+ * - ALL-PAIRS (an exact run whose `n x n` f32 matrix fits one binding, weighted, or unweighted up to
+ *   `ALL_PAIRS_MAX_NODES`): `allPairsShortestPath`'s blocked Floyd-Warshall sweep, then `closeness-rowsum` folds each row on
+ *   the device -- hop counts as exact integers, weighted distances and harmonic reciprocals in f32 -- and only `n`
+ *   words come back. Weighted scores agree with the one-search-per-source route up to f32 rounding of the sums.
+ * - LEVELS (unweighted, every other case): a bit-parallel multi-source breadth-first search, `32 x words` sources per
+ *   batch (up to `MAX_WORDS` = 8 words, 256 sources), ONE `closeness-level` dispatch per level. Each level chooses on
+ *   the device between pushing the frontier over the out-arcs (one invocation per arc) and pulling it over the
+ *   in-arcs (one invocation per node, with an early exit once every source has reached the node), from the arcs the
+ *   frontier would push against `pullAt`; a graph with a node of more than `PULL_MAX_DEGREE` in-arcs only pushes. The levels of a
+ *   submit tally their claims per source into one count table, read back once per submit; the host folds the counts
+ *   into exact sums in f64 (`count x distance`) and harmonic sums (`count / distance`). A level whose predecessor
+ *   claimed nothing returns at once, so recording `MAX_LEVELS_PER_SUBMIT` levels costs little past a batch's depth.
+ * - ONE SEARCH PER SOURCE (weighted above the all-pairs ceiling, or a weighted sampled run): one `sssp` per source,
+ *   the sums reduced on the host between calls.
+ *
+ * `weighted` defaults to the snapshot's `flags.weighted`; `weighted: false` on a weighted snapshot ignores the column;
+ * `weighted: true` over unit weights or no column is the unweighted problem. `maxIterations` and `tolerance` are the
  * seam's placeholder keys and an exact traversal has neither, so a defined value is REFUSED before any device work
- * (`E_UNSUPPORTED { option }`, the package's rule for an option it does not implement, PD-25); `undefined` is legal.
- * `iterations` reports the source batches run (the sources, on the weighted route), `converged` is always true.
- * A SAMPLED run (`sources`, issue #426; undirected snapshots only) seeds its batches from the listed sources (the
- * reduce's role 2 reads the list the host wrote after the per-node sums in `perSource`), and the sweep also adds each
- * claim's distance into a per-node sum (`perNode`), read back with every submit and folded on the host in f64 into
- * `1 / sum` per NODE, where the exact run folds per SOURCE: on an undirected graph the distance from a source to a node
- * is the distance from the node to the source, which is what the CPU port's sampled closeness sums.
+ * (`E_UNSUPPORTED { option }`); `undefined` is legal. `iterations` reports the source batches run (the sources, on the
+ * one-search-per-source route; 1 on the all-pairs route), `converged` is always true.
+ *
+ * A SAMPLED run (`sources`, undirected snapshots only) seeds its batches from the listed sources and adds every
+ * claim's distance into a per-node sum, folded on the host into `1 / sum` per NODE: on an undirected graph the
+ * distance from a source to a node is the distance from the node to the source, which is what the CPU port's sampled
+ * closeness sums. A sampled harmonic run is refused (`E_UNSUPPORTED closenessCentrality.sampledHarmonic`): the
+ * per-node reciprocal sums would need a float atomic.
  *
- * Cost, stated so nobody is surprised: closeness is O(n x m) on any device -- at 1M nodes it is 31,250 batches of a
- * full multi-source traversal, minutes on the card, and no target in design 10.4 asks for less. `compact.record`
- * leases its offsets and the scan's block sums afresh on every call, once per LEVEL here, so the planner is given a
- * scope whose `scratch` hands the same buffer back for the same label and size: the dispatches of one pass run in
- * order, a level's scan overwrites the previous level's, and the run holds one set instead of `levels x batches`.
- * The sweep keeps DEP-P8-E's refusal of a windowed core (`assertWholeCore`): the bit-parallel claim needs the whole
- * arc array bound. The tuning entry `closenessWithTuning` (PD-26's shape) is what the tests drive; nothing public
- * exposes it.
+ * Cost, stated so nobody is surprised: closeness is O(n x m) on any device -- at 1M nodes it is 3,907 batches of a
+ * full multi-source traversal. The level kernel binds the whole arc array (`assertWholeCore`) and, on a directed
+ * snapshot, the whole reverse adjacency. `closenessWithTuning` is what the tests drive; nothing public exposes it.
  */
 import { type GraphSnapshot } from "@graphty/graph-format";
 import { type GpuContext } from "../context.js";
@@ -46,17 +46,20 @@ import { type GpuRunOptions } from "../types/run.js";
 /**
  * Closeness centrality on the device (spec 3.3 line 810, design 8.4, 9.7): `scores[s] = 1 / sumDist_s` over the finite
  * distances from `s` to every other node, `0` when nothing is reached -- the legacy default of `@graphty/algorithms`'
- * `closenessCentrality`, unweighted by one bit-parallel multi-source search per 32 sources, weighted by one `sssp`
- * per source; `weighted` defaults to the snapshot's flag, `maxIterations` / `tolerance` are refused when defined
- * (PD-25). `iterations` is the source batches run and `converged` is always true.
+ * `closenessCentrality` -- or, with `harmonic`, the sum of `1 / dist` over the same nodes. Small and weighted
+ * graphs whose all-pairs matrix fits one binding run the all-pairs sweep and a row sum; other unweighted graphs run a
+ * bit-parallel multi-source search of up to 256 sources per batch; weighted graphs above the all-pairs ceiling run one
+ * `sssp` per source. `weighted` defaults to the snapshot's flag, `maxIterations` / `tolerance` are refused when
+ * defined. `iterations` is the source batches run and `converged` is always true.
  *
  * SAMPLED (`sources`, node indices, duplicates run twice; undirected snapshots only, E_UNSUPPORTED
- * `closenessCentrality.directedSources` otherwise): the batches seed the listed sources instead of every node, and
- * each node's score is `1 / sum` of its distances to the sources that reach it (itself excluded), `0` when none does:
- * the sampled score of the CPU port, unscaled. `sourcesUsed` is the list's length (`n` exact).
+ * `closenessCentrality.directedSources` otherwise; not with `harmonic`, E_UNSUPPORTED
+ * `closenessCentrality.sampledHarmonic`): the batches seed the listed sources instead of every node, and each node's
+ * score is `1 / sum` of its distances to the sources that reach it (itself excluded), `0` when none does: the sampled
+ * score of the CPU port, unscaled. `sourcesUsed` is the list's length (`n` exact).
  * @param ctx - the context whose device runs the kernels
  * @param s - the snapshot (uploaded through ctx.residency, or found there)
- * @param options - `weighted`, `sources`, plus dest (a Float32Array of length n for `scores`) / signal / onProgress
+ * @param options - `weighted`, `harmonic`, `sources`, plus dest (a Float32Array of length n for `scores`) / signal / onProgress
  * @returns the scores, the batches run, `converged: true`, `precision: "f32"` and `sourcesUsed`
  */
 export declare function closenessCentrality(ctx: GpuContext, s: GraphSnapshot, options?: ClosenessAcceleratorOptions & HitsOptionsLike & GpuRunOptions): Promise<GpuClosenessResult>;

package/dist/src/algorithms/closeness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"closeness.d.ts","sourceRoot":"","sources":["../../../src/algorithms/closeness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAY,KAAK,aAAa,EAAY,MAAM,uBAAuB,CAAC;AAG/E,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAiBhD,OAAO,EAAE,KAAK,2BAA2B,EAAE,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACjG,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAgZrD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAC/B,GAAG,EAAE,UAAU,EACf,CAAC,EAAE,aAAa,EAChB,OAAO,CAAC,EAAE,2BAA2B,GAAG,eAAe,GAAG,aAAa,GACxE,OAAO,CAAC,kBAAkB,CAAC,CAE7B"}
+{"version":3,"file":"closeness.d.ts","sourceRoot":"","sources":["../../../src/algorithms/closeness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGrE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAOhD,OAAO,EAAE,KAAK,2BAA2B,EAAE,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACjG,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAyfrD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAC/B,GAAG,EAAE,UAAU,EACf,CAAC,EAAE,aAAa,EAChB,OAAO,CAAC,EAAE,2BAA2B,GAAG,eAAe,GAAG,aAAa,GACxE,OAAO,CAAC,kBAAkB,CAAC,CAE7B"}