Spectral Modularity Maximization

SQL function: cugraph_spectral_modularity_maximization

Cluster vertices with spectral modularity maximization.

Signature

cugraph_spectral_modularity_maximization(table_name [, src_col, dst_col [, weight_col [, options_json]]])

Allowed argument counts: 1, 3, 4, 5.

Quickstart

SELECT * FROM cugraph_spectral_modularity_maximization('target_edges')

Positional arguments

Argument	Type	Required	Default	Notes
table_name	Utf8	yes
src_col	Utf8	no	src
dst_col	Utf8	no	dst
weight_col	Utf8|null	no		accepted as an edge-column binding; native algorithm execution does not consume weights; semantic effect: none for this algorithm
options_json	Utf8	no

JSON options

Option	Type	Default	Constraints	Description
evs_max_iterations	UInt32	500	min 1; max 2147483647
evs_tolerance	Float64	0.01	min 0
k_means_max_iterations	UInt32	100	min 1; max 2147483647
k_means_tolerance	Float64	0.001	min 0
n_clusters	UInt32	2	min 1
n_eigenvectors	UInt32	2	min 1
seed	UInt64	0

Graph construction options

Shared by all cuGraph functions, shown here with this function's defaults. The construction_policy option controls whether Nexus requests Python cuGraph-compatible edge normalization or bypasses it for raw libcugraph-style construction; see graph construction options for the full policy guide.

Option	Type	Default	Constraints	Description
construction_policy	Utf8	"python_cugraph"	one of "python_cugraph", "raw_libcugraph"	Edge-list construction semantics used before calling libcugraph.
directed	Boolean	false		Whether graph construction treats edges as directed.
renumber	Boolean	true		Whether graph construction may renumber external vertex identifiers internally.

Output schema

Column	Type	Nullable	Description
vertex	Int64	no	Vertex assigned to a spectral clustering partition.
partition	Int64	no	Cluster identifier assigned by spectral modularity maximization.

note

These are the generic registry schemas. Run cugraph_validate_call for the concrete, table-specific output schema of a particular call.

Examples

Canonical call (generic table/column names):

SELECT * FROM cugraph_spectral_modularity_maximization('target_edges')

Dataset-specific examples

TODO: add runnable examples against a concrete dataset (edge table, real vertex ids, expected output). These are intentionally left for a follow-up.

Limitations & notes

• dry-run validates table resolution, column presence, static dtypes, and options only
• dry-run does not scan edge data, construct a graph, or prove source-vertex existence
• legacy cuGraph implementation requires Int32 source and destination vertex columns
• cuGraph requires directed=false so the graph is constructed as an undirected/symmetric view

Validate before running

Always dry-run a call before executing it. Validation checks the function, table, columns, dtypes, and options without touching the GPU:

SELECT * FROM cugraph_validate_call(
  'cugraph_spectral_modularity_maximization',
  'your_edges_table',
  '{"src_col":"src","dst_col":"dst"}'
);

See Discovery & validation for the full cugraph_validate_call contract.