Spectral Modularity Maximization
UDTF: 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
Every edge_id column must have the integer type of src and dst.
Named value arguments
Graph construction options
This UDTF requires directed=false (undirected/symmetric graph); all other graph construction options follow the shared defaults documented in Graph Construction Options.
Output
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.
How does the dense citation core divide into six research groups?
A six-group view of the dense citation core can show which catalog fields
dominate each group and where labels mix. The query first keeps papers with at
least 30 neighbors in the undirected citation graph, then partitions that core
and reports each group's two most common primary_fos labels. It renumbers
paper IDs with a dense mapping
for the algorithm's Int32 input requirement.
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;
The largest reported cluster has 28,994 papers, with convolutional neural network and object detection as its two most common labels. Other rows include probabilistic encryption, fuzzy logic, and rough set labels in smaller clusters. The table shows only the top two labels per cluster, and cluster ids are arbitrary.
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.