Skip to content

feat(experimental): add progressive GPU force-directed graph layout - #2952

Merged
ibgreen-openai merged 1 commit into
masterfrom
codex/lugraph-force-layout
Aug 7, 2026
Merged

feat(experimental): add progressive GPU force-directed graph layout#2952
ibgreen-openai merged 1 commit into
masterfrom
codex/lugraph-force-layout

Conversation

@ibgreen-openai

@ibgreen-openai ibgreen-openai commented Aug 5, 2026

Copy link
Copy Markdown
Collaborator

Goals

  • Add progressive, browser-native GPU force-directed graph layout using position buffers that rendering can consume directly without copying.
  • Support deterministic initialization, pinned nodes, configurable physics, and warm-started iterations per frame.
  • Stack narrowly on the verified luGraph PageRank/adjacency foundations in feat(experimental): add GPU PageRank with dangling redistribution #2946 without claiming ForceAtlas2 or unsupported floating-point atomics.

Changes

  • Add LuGraphForceLayout and LuGraphForceLayoutProps exclusively to @luma.gl/experimental/lugraph.
  • Require caller-owned packed GPUVector<'float32x2'> positions with both STORAGE and VERTEX usage, plus independent packed float32x2 velocity storage.
  • Compute exact tiled O(V² + E) all-vertex repulsion, symmetric incoming/outgoing edge attraction, origin gravity, damping, integration timestep, and bounded velocity.
  • Separate globally synchronized force and integration passes; preserve stable read-only positions during force accumulation without graph-owned scratch or floating-point atomics.
  • Require reverse CSR for directed graphs so every edge contributes symmetric physical attraction; reuse forward CSR for undirected graphs and explicitly ignore optional edge weights.
  • Support caller-owned uint32 pin masks, deterministic seeded one-shot GPU reset controls, and persistent warm starts across repeated encodings.
  • Preserve positions and clear velocities on required adjacency overflow; preserve pinned positions and clear pinned velocities.
  • Support aligned four-byte-offset vector storage, bounded three-dimensional dispatch, uniform shared-memory tile barriers, and portable eight-or-fewer storage bindings.
  • Add 77 focused Node contracts and 23 real-WebGPU CPU-oracle scenarios covering exact forces, deterministic reset, pinning, overflow, rendering-compatible ownership, velocity clipping, repeated progression, and actual [2,2,2] tiled dispatch over 1,025 vertices.

Verification

  • nvm use: passed (Node v22.22.1).
  • yarn install: attempted normally and with escalation; configured registry rejects unavailable dependencies with HTTP 403. Verification uses an isolated APFS-cloned compatible dependency tree and ignored Yarn state; no package/lockfile changes.
  • yarn lint fix: passed (1,552 files).
  • Final yarn build: passed across every workspace after final WGSL, test, and formatting changes.
  • Focused Node force-layout tests: 77 passed.
  • Focused real Chromium/WebGPU force-layout tests: 23 passed.
  • Complete CI=1 yarn test: 883 Node tests and 1,672 real Chromium/WebGPU tests passed; existing skips only.
  • yarn website:build: passed.
  • (cd website && yarn build): passed.
  • yarn examples:typecheck: all 46 example workspaces passed.
  • yarn bundle-size: all seven bundle-size budgets passed.
  • Built ESM and CommonJS package-subpath smoke checks: passed; LuGraphForceLayout remains absent from the experimental root.
  • Normal commit hooks: lint and all 883 Node tests passed.

Risks and follow-up

  • Repulsion is exact and intentionally quadratic; scalable approximate spatial acceleration is a separate follow-up, not misrepresented as exact ForceAtlas2.
  • Directed layout explicitly requires reverse adjacency; edge weights are retained by topology but intentionally ignored by this initial unweighted spring model.
  • Every workgroup invocation participates uniformly in tiled shared-memory barriers; no device-wide shader barrier, floating-point atomic, CPU readback, or implicit command submission is used.
  • Stacked on feat(experimental): add GPU PageRank with dangling redistribution #2946; target codex/lugraph-pagerank until prerequisites land.

@ibgreen-openai
ibgreen-openai marked this pull request as ready for review August 5, 2026 01:51
@ibgreen-openai
ibgreen-openai force-pushed the codex/lugraph-pagerank branch 4 times, most recently from 1cbe6a3 to 9cb4627 Compare August 7, 2026 00:00
Base automatically changed from codex/lugraph-pagerank to master August 7, 2026 00:21
@ibgreen-openai
ibgreen-openai force-pushed the codex/lugraph-force-layout branch from 3f7c62a to 15de864 Compare August 7, 2026 00:28
@ibgreen-openai
ibgreen-openai force-pushed the codex/lugraph-force-layout branch from 15de864 to fc6e621 Compare August 7, 2026 00:36
@ibgreen-openai
ibgreen-openai merged commit a0b8575 into master Aug 7, 2026
4 checks passed
@ibgreen-openai
ibgreen-openai deleted the codex/lugraph-force-layout branch August 7, 2026 00:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants