Skip to content

feat(experimental): add spatially accelerated GPU graph force layout - #2957

Open
ibgreen-openai wants to merge 14 commits into
codex/lugraph-interactive-explorerfrom
codex/lugraph-spatial-force-layout
Open

feat(experimental): add spatially accelerated GPU graph force layout#2957
ibgreen-openai wants to merge 14 commits into
codex/lugraph-interactive-explorerfrom
codex/lugraph-spatial-force-layout

Conversation

@ibgreen-openai

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

Copy link
Copy Markdown
Collaborator

Goals

  • Add an explicitly approximate, GPU-native spatial acceleration path for progressive luGraph layouts without calling it Barnes–Hut, ForceAtlas2, or exact all-pairs repulsion.
  • Preserve caller-owned renderable coordinates, explicit grid memory/capacity/status, portable WebGPU bindings, and bounded three-dimensional dispatch.

Changes

  • Introduce optional-subpath-only LuGraphSpatialForceLayout, composing an existing LuGraphForceLayout with caller-owned grid offsets, stable IDs, float32 cell centers, accepted counts, overflow flags, bounds, opening threshold, and exact near-cell radius.
  • Rebuild the existing GPU uniform-grid index every iteration and gather per-cell centers from grouped vertex IDs without floating-point atomics.
  • Compute nearby repulsion exactly, approximate sufficiently distant cells with population-weighted monopoles, and preserve every remaining interaction; theta: 0 executes exact interactions across all cells.
  • Preserve directed/undirected attraction, deterministic reset, warm starts, pinned vertices, velocity clipping, render-bindable positions, and explicit GPU synchronization.
  • Fail closed on out-of-domain vertices, insufficient index capacity, or required topology overflow while preserving positions and clearing velocities.
  • Add 83 focused Node validation/ownership cases and 27 real Chromium/WebGPU CPU-oracle cases, including exact-versus-approximate error, grid offsets/centroids, zero vertices, 4-byte views, reset/pinning, and 1,025-vertex/1,025-cell synthetic 3D dispatch.

Verification

  • nvm use: passed; Node v22.22.1.
  • yarn install: attempted but blocked by HTTP 403 for unpublished/uncached dev-tools dependencies. Used an isolated APFS copy-on-write clone of an existing compatible dependency tree; no dependency or lockfile changes.
  • yarn lint fix: passed; 1,561 files checked.
  • yarn build: passed after final formatting.
  • Focused Node tests: 83 passed.
  • Focused real Chromium/WebGPU CPU-oracle tests: 27 passed.
  • Complete yarn test: 975 Node tests passed, 1 skipped; 1,701 real-browser/WebGPU tests passed, 25 skipped.
  • yarn website:build: passed.
  • (cd website && yarn build): passed.
  • yarn examples:typecheck: passed across 46 example workspaces.
  • yarn bundle-size: all seven production bundle ceilings passed.

Risks / follow-up

  • This is a flat uniform-grid monopole approximation, not hierarchical Barnes–Hut or ForceAtlas2.
  • Complexity is O(V × C + local pairs + E) plus one explicit index rebuild per iteration, with caller-owned O(V + C) grid storage.
  • The next stacked change adds explicitly started, CPU-oracle-validated live benchmarks with separate index/upload/readback timings and approximation-error reporting.

@ibgreen-openai
ibgreen-openai marked this pull request as ready for review August 5, 2026 02:23
@ibgreen-openai
ibgreen-openai force-pushed the codex/lugraph-interactive-explorer branch from 5c18358 to 8be314c Compare August 7, 2026 01:03
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