Spectral Modularity Maximization

SQL function: cugraph_spectral_modularity_maximization

Official cuGraph reference: C API

Partition vertices by embedding the graph with leading modularity eigenvectors and clustering that embedding with k-means.

Signature

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

Relation inputs

The first positional argument names a registered edge table or view (the edges role). Parenthesized relation subqueries are not accepted; metadata validation uses the same registered name.

Vertex ID types

The edges relation declares the accepted vertex-ID domains. Numeric calls preserve the existing numeric schema. When logical string support is declared, Utf8, LargeUtf8, and Utf8View endpoint columns share one logical domain; their vertex-identity outputs are canonicalized to Utf8.

Domain	Accepted endpoint inputs	Output contract
Numeric edge endpoints	Int32	Vertex identity output columns remain numeric.
Logical string edge endpoints	Not supported	No canonical string output is declared.

This is a legacy Int32-only vertex-ID contract; logical string endpoints are not supported.

Scalar arguments & JSON options

Positional scalar arguments

src_col and dst_col name the edge endpoint columns; both are optional and default to src and dst.

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

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

This function builds an undirected graph by default (directed=false); all other graph construction options follow the shared defaults documented in Graph Construction Options.

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.

These are generic descriptor schemas; validate the call to get the concrete, table-specific output schema.

Examples

This example runs on the citation network demo dataset.

Peel the satellite fields off the dense citation core

This cuGraph C API algorithm needs Int32 vertex ids, and AMiner paper ids overflow Int32 — so the example uses the SQL renumbering pattern on a graph worth clustering: the k=30 citation core (every paper keeps at least 30 combined in+out citation links inside the subgraph, as in the k-core example). One algorithm's output becomes the next algorithm's input, with a window function in between:

CREATE TABLE kcore30_edges AS
SELECT src, dst FROM cugraph_k_core('citation_edges', 'src', 'dst', NULL, '{"k": 30}');

CREATE TABLE kcore_vertex_ids AS
SELECT paper_id, CAST(ROW_NUMBER() OVER (ORDER BY paper_id) AS INT) AS vid
FROM (SELECT src AS paper_id FROM kcore30_edges UNION SELECT dst FROM kcore30_edges);

CREATE VIEW kcore30_i32 AS
SELECT a.vid AS src, b.vid AS dst
FROM kcore30_edges e
JOIN kcore_vertex_ids a ON a.paper_id = e.src
JOIN kcore_vertex_ids b ON b.paper_id = e.dst;

WITH labeled AS (
  SELECT s."partition" AS cluster, p.primary_fos
  FROM cugraph_spectral_modularity_maximization('kcore30_i32', 'src', 'dst', NULL,
    '{"n_clusters": 6, "n_eigenvectors": 6,
      "evs_tolerance": 0.00001, "evs_max_iterations": 2000,
      "k_means_max_iterations": 1000}') s
  JOIN kcore_vertex_ids v ON v.vid = s.vertex
  JOIN papers p ON p.paper_id = v.paper_id),
counts AS (
  SELECT cluster, primary_fos, COUNT(*) AS n FROM labeled GROUP BY 1, 2),
ranked AS (
  SELECT cluster, primary_fos, n,
         SUM(n) OVER (PARTITION BY cluster) AS members,
         ROW_NUMBER() OVER (PARTITION BY cluster ORDER BY n DESC) AS rn
  FROM counts)
SELECT cluster, members, primary_fos, n
FROM ranked WHERE rn <= 2
ORDER BY members DESC, rn;

cluster	members	primary_fos	n
0	28,994	Convolutional neural network	1,112
0	28,994	Object detection	912
4	2,298	Probabilistic encryption	115
4	2,298	Encryption	113
2	1,089	Fuzzy logic	159
2	1,089	Group decision-making	122
5	787	Dominance-based rough set approach	168
5	787	Rough set	160
3	142	Feature selection	8
3	142	Software metric	8
1	79	Recursive least squares filter	11
1	79	Iterative method	8

The spectral embedding keeps the deep-learning/vision nucleus in one 28,994- paper cluster and peels off coherent satellite literatures: a cryptography cluster, a fuzzy-logic/decision-making cluster, and a rough-set-theory cluster. That shape is characteristic of this algorithm on scale-free graphs — it will not carve a power-law nucleus into equal parts (asking Louvain or Leiden does that better); what it answers is "which satellite communities are spectrally separable from the core, given exactly n_clusters slots". The tight evs_tolerance matters; the loose default stops the eigensolver early and the satellites smear into the nucleus. Cluster ids are arbitrary and k-means may move a few boundary papers between runs — snapshot with CREATE TABLE ... AS per the demo dataset guide before building on the labels.

Limitations & lifecycle

• cuGraph C API edge-type dispatch requires Int32 source and destination vertex columns
• cuGraph requires directed=false so the graph is constructed as an undirected/symmetric view

Validate before running

Dry-run validation checks registered relation metadata, column presence, static dtypes, and options only; it does not scan edge data, construct a graph, or prove source-vertex existence:

SELECT * FROM gpu_validate_call(
  'cugraph_spectral_modularity_maximization',
  '{"schema_version":1,"relations":{"edges":{"table":"target_edges"}},"options":{"src_col":"src","dst_col":"dst"}}'
);

See GPU Function Catalog API for the full gpu_validate_call contract.