Skip to content

feat(experimental): add deterministic GPU graph communities - #2963

Open
ibgreen-openai wants to merge 7 commits into
codex/lugraph-deck-integrationfrom
codex/lugraph-label-propagation
Open

feat(experimental): add deterministic GPU graph communities#2963
ibgreen-openai wants to merge 7 commits into
codex/lugraph-deck-integrationfrom
codex/lugraph-label-propagation

Conversation

@ibgreen-openai

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

Copy link
Copy Markdown
Collaborator

Goals

  • Complete the explicitly requested GPU-resident community-exploration capability with deterministic, clearly documented label propagation.
  • Distinguish densely connected communities inside a single weakly connected component without claiming Louvain, Leiden, or modularity optimization.

Changes

  • Export LuGraphLabelPropagation and its typed props exclusively from the optional @luma.gl/experimental/lugraph entry point.
  • Initialize stable vertex-ID labels and run bounded, synchronously separated majority-voting passes over weak neighborhoods.
  • Require reverse adjacency for directed graphs; use symmetric forward adjacency once for undirected graphs.
  • Include exactly one self vote, ignore self-loop edges, count duplicate/reciprocal original edges independently, and resolve every support tie with the lowest stable label.
  • Preserve source chunks and caller-owned outputs, allocate only one graph-owned snapshot, respect physical-buffer alias isolation, and stay within the portable eight-storage-binding limit.
  • Publish optional GPU-resident final-iteration convergence, preserve isolated vertices, and fail closed on the selected forward/reverse topology overflow.
  • Scale dispatch using the existing bounded multidimensional helpers, including real synthetic three-dimensional execution.
  • Document actual deterministic heuristic semantics, O(sum(degree²)) work per iteration, bounded nonconvergence, and explicit non-equivalence to Louvain/Leiden.
  • Add comprehensive constructor/ownership Node tests and real Chromium/WebGPU CPU-oracle coverage, including two bridged dense cliques that remain distinct communities although weak components merge them.

Verification

  • nvm use: passed; Node v22.22.1.
  • yarn install: attempted; unpublished dev-tools dependencies return HTTP 403. Used an independent APFS clone of existing compatible dependencies without lockfile changes.
  • yarn lint fix: passed after implementation; 1,576 files checked.
  • yarn build: passed across all modules, including the optional luGraph ESM/CommonJS/types exports.
  • Focused Node community validation: 47 passed.
  • Focused actual Chromium/WebGPU community CPU oracles: 25 passed.
  • Complete Node suite: 1,073 passed, 1 skipped on the final propagated head.
  • yarn test: passed on the final stacked head; 1,073 Node tests and 1,734 actual Chromium/WebGPU browser tests passed (25 browser tests skipped).
  • yarn website:build: passed on the final stacked head.
  • (cd website && yarn build): passed on the final stacked head.
  • yarn examples:typecheck: all 46 example workspaces passed.
  • yarn bundle-size: all seven production bundle ceilings passed.

Risks

  • Synchronous neighborhood majority voting is a bounded heuristic and may oscillate or remain unconverged; the optional real GPU scalar reports only the final fixed-point result.
  • Worst-case per-iteration work is O(sum(degree²)); this is intentionally not Louvain, Leiden, or modularity optimization.
  • Directed inputs need reverse CSR; required topology overflow invalidates community outputs instead of silently returning incomplete results.

@ibgreen-openai
ibgreen-openai marked this pull request as ready for review August 5, 2026 03:32
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