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]]])

Quickstart

The call below expects a registered edge table or view target_edges with endpoint columns src and dst. Substitute your own registered relations.

SELECT * FROM cugraph_spectral_modularity_maximization('target_edges');

Inputs

table_name must be a registered edge table or view (the edges role); parenthesized subqueries are not accepted, and metadata validation resolves the same registered name.

Endpoint columns accept Int32 vertex IDs only; logical string endpoints are not supported (legacy Int32-only contract). The shared vertex-ID contract is summarized in Vertex ID support; the concrete call-specific schema comes from gpu_validate_call.

Arguments and 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	Maximum eigenvalue-solver iterations.
evs_tolerance	Float64	0.01	min 0	Convergence tolerance for the eigenvalue solver. Smaller values compute a more accurate embedding at higher cost.
k_means_max_iterations	UInt32	100	min 1; max 2147483647	Maximum k-means iterations.
k_means_tolerance	Float64	0.001	min 0	Convergence tolerance for the k-means stage.
n_clusters	UInt32	2	min 1	Number of clusters the k-means stage assigns.
n_eigenvectors	UInt32	2	min 1	Number of leading eigenvectors computed for the spectral embedding that k-means clusters.
seed	UInt64	0		Seed for the random initialization (Lanczos start vector and k-means centroid seeding). It does not make the partition bit-identical across runs; same-seed replays may land in a different but equally valid assignment.

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

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.

Limits

• 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 the call

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.