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.

Quickstart

The call below supplies edges from registered relation target_edges with canonical src and dst columns and may include weight. Substitute your own registered relations.

SELECT * FROM cugraph_spectral_modularity_maximization(edges => (SELECT src, dst FROM target_edges));

Inputs

Every relation is a named parenthesized SELECT subquery. The required edges role uses canonical src and dst columns; every role, its canonical columns, and their accepted Arrow types are listed under Relation arguments. Metadata validation resolves registered tables named in its JSON request.

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

Relation arguments

Argument	Required	Columns	Description
edges	yes	src, dst: Int32 weight (optional): Float32, Float64 edge_id (optional): Int32	edge relation with canonical src and dst columns, plus optional weight and edge_id columns

Every edge_id column must have the integer type of src and dst.

Named value arguments

Option	Type	Default	Constraints	Description
evs_max_iterations	integer	500	min 1; max 2147483647	eigenvalue solver iteration limit
evs_tolerance	number	0.01	min 0	non-negative eigenvalue solver tolerance
k_means_max_iterations	integer	100	min 1; max 2147483647	k-means iteration limit
k_means_tolerance	number	0.001	min 0	non-negative k-means tolerance
n_clusters	integer	2	min 1; max 4294967295	number of spectral clusters
n_eigenvectors	integer	2	min 1; max 4294967295	number of spectral eigenvectors
seed	integer	0	min 0; max 18446744073709552000	random initialization seed

Graph construction options

This function requires directed=false (undirected/symmetric graph); 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; run gpu_validate_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 citation neighbors 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 OR REPLACE TABLE kcore30_edges AS
SELECT src, dst
FROM cugraph_k_core(edges => (SELECT src, dst FROM citation_edges), k => 30);

CREATE OR REPLACE 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 OR REPLACE 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(
    edges => (SELECT src, dst FROM kcore30_i32), 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 OR REPLACE 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

To dry-run validate relation metadata, column types, and options without execution, see gpu_validate_call.