API reference

GraphEmbedder

GraphEmbedder accepts exactly one undirected simple graph through either a SciPy-compatible adjacency matrix or a CUDA/array-compatible edge list. The device keyword controls the shared Torch spectral function; the remaining layout path is always CUDA/RAPIDS. Production calls should pass device="cuda" explicitly. midpoint_query_batch_size configures exact cuVS query batches from 1 through the canonical hard ceiling of 64; it does not change the midpoint reference, search method, adaptive cutoff proof, or distance/global-edge-ID result order. Each returned query row must contain unique global edge IDs; validation occurs before negative-distance repair.

class graphem_rapids.GraphEmbedder(adjacency=None, n_components=2, L_min=1.0, k_attr=0.2, k_inter=0.5, n_neighbors=10, sample_size=256, seed=0, verbose=True, logger_instance=None, *, device='cuda', midpoint_query_batch_size=64, edges=None, n_vertices=None)[source]

Embed one undirected simple graph with the canonical GraphEm dynamics.

Exactly one of adjacency or edges must be supplied. The graph must be loop-free, duplicate-free, and large enough for the requested block eigenspace and midpoint neighbourhood. Disconnected graphs and isolated vertices use the same normalized-Laplacian convention as connected graphs.

Parameters:

  • n_components (int)

  • L_min (float)

  • k_attr (float)

  • k_inter (float)

  • n_neighbors (int)

  • sample_size (int)

  • seed (int)

  • verbose (bool)

  • logger_instance (Optional[logging.Logger])

  • midpoint_query_batch_size (int)

  • n_vertices (Optional[int])

update_positions()[source]

Apply one complete spring, crossing, update, and normalization step.

run_layout(num_iterations=100)[source]

Run exactly num_iterations complete GraphEm steps.

Parameters:

num_iterations (int)

get_positions(as_numpy=True)[source]

Return the complete embedding positions.

Parameters:

as_numpy (bool)

get_scores(as_numpy=True)[source]

Return Euclidean radius for every vertex.

Parameters:

as_numpy (bool)

get_top_k(k, as_numpy=True)[source]

Return vertex IDs ordered by decreasing radius and then ID.

Parameters:

  • k (int)

  • as_numpy (bool)

get_diagnostics()[source]

Return configuration and primitive timing scopes for this instance.

Graph generators

Generators return symmetric SciPy CSR adjacency matrices. GraphEmbedder then enforces its binary simple-graph contract; see Graph Generators for the scale-free multiedge caveat.

Graph generators for Graphem.

This module provides various functions to generate different types of graphs. All generators return sparse adjacency matrices instead of simple edge lists.

graphem_rapids.generators.generate_er(n, p, seed=0)[source]

Generate a random undirected graph using the Erdős–Rényi G(n, p) model.

Parameters:

  • n – int Number of vertices.

  • p – float Probability that an edge exists between any pair of vertices.

  • seed – int Random seed for reproducibility.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency

graphem_rapids.generators.compute_vertex_degrees(adjacency)[source]

Compute the degree of each vertex from the adjacency matrix.

Parameters:

adjacency – scipy.sparse matrix Sparse adjacency matrix

Returns:

np.array of shape (n,) with degree of each vertex

Return type:

degrees

graphem_rapids.generators.generate_sbm(n_per_block=75, num_blocks=4, p_in=0.15, p_out=0.01, labels=False, seed=0)[source]

Generate a stochastic block model graph.

Parameters:

  • n_per_block – int Number of vertices per block.

  • num_blocks – int Number of blocks.

  • p_in – float Probability of edge within a block.

  • p_out – float Probability of edge between blocks.

  • labels – bool If True, return vertex labels.

  • seed – int Random seed for reproducibility.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

labels: np.ndarray of shape (n,) (only if labels=True)

Block labels for each vertex.

Return type:

adjacency

graphem_rapids.generators.generate_ba(n=300, m=3, seed=0)[source]

Generate a Barabási-Albert preferential attachment graph.

Parameters:

  • n – int Number of vertices.

  • m – int Number of edges to attach from a new vertex to existing vertices.

  • seed – int Random seed for reproducibility.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency

graphem_rapids.generators.generate_ws(n=1000, k=6, p=0.3, seed=0)[source]

Generate a Watts-Strogatz small-world graph.

Parameters:

  • n – int Number of vertices.

  • k – int Each vertex is connected to k nearest neighbors in ring topology.

  • p – float Probability of rewiring each edge.

  • seed – int Random seed for reproducibility.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency

graphem_rapids.generators.generate_power_cluster(n=1000, m=3, p=0.5, seed=0)[source]

Generate a powerlaw cluster graph.

Parameters:

  • n – int Number of vertices.

  • m – int Number of random edges to add per new vertex.

  • p – float Probability of adding a triangle after adding a random edge.

  • seed – int Random seed for reproducibility.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency

graphem_rapids.generators.generate_road_network(width=30, height=30)[source]

Generate a 2D grid graph representing a road network.

Parameters:

  • width – int Width of the grid.

  • height – int Height of the grid.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency

graphem_rapids.generators.generate_bipartite_graph(n_top=50, n_bottom=100, p=0.1, seed=0)[source]

Generate a random bipartite graph.

Parameters:

  • n_top – int Number of vertices in the top set.

  • n_bottom – int Number of vertices in the bottom set.

  • p – float Probability of edge between any vertex in top set and any vertex in bottom set.

  • seed – int Random seed for reproducibility.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency

graphem_rapids.generators.generate_complete_bipartite_graph(n_top=50, n_bottom=100)[source]

Generate a complete bipartite graph.

In a complete bipartite graph, every vertex in the top set is connected to every vertex in the bottom set, resulting in n_top * n_bottom edges.

Parameters:

  • n_top – int Number of vertices in the top set.

  • n_bottom – int Number of vertices in the bottom set.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency

graphem_rapids.generators.generate_balanced_tree(r=2, h=10)[source]

Generate a balanced r-ary tree of height h.

Parameters:

  • r – int Branching factor of the tree.

  • h – int Height of the tree.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency

graphem_rapids.generators.generate_random_regular(n=100, d=3, seed=0)[source]

Generate a random regular graph where each node has degree d.

Parameters:

  • n – int Number of vertices.

  • d – int Degree of each vertex.

  • seed – int Random seed for reproducibility.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency

graphem_rapids.generators.generate_scale_free(n=100, alpha=0.41, beta=0.54, gamma=0.05, delta_in=0.2, delta_out=0, seed=0)[source]

Generate a scale-free graph using Holme and Kim algorithm.

Parameters:

  • n – int Number of vertices.

  • alpha – float Parameters for the scale-free graph generation.

  • beta – float Parameters for the scale-free graph generation.

  • gamma – float Parameters for the scale-free graph generation.

  • delta_in – float Parameters for the scale-free graph generation.

  • delta_out – float Parameters for the scale-free graph generation.

  • seed – int Random seed for reproducibility.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency

graphem_rapids.generators.generate_geometric(n=100, radius=0.2, dim=2, seed=0)[source]

Generate a random geometric graph in a unit cube.

Parameters:

  • n – int Number of vertices.

  • radius – float Distance threshold for connecting vertices.

  • dim – int Dimension of the space.

  • seed – int Random seed for reproducibility.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency

graphem_rapids.generators.generate_caveman(l=10, k=10)[source]

Generate a caveman graph with l cliques of size k.

Parameters:

  • l – int Number of cliques.

  • k – int Size of each clique.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency

graphem_rapids.generators.generate_relaxed_caveman(l=10, k=10, p=0.1, seed=0)[source]

Generate a relaxed caveman graph with l cliques of size k, and a rewiring probability p.

Parameters:

  • l – int Number of cliques.

  • k – int Size of each clique.

  • p – float Rewiring probability.

  • seed – int Random seed for reproducibility.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency

graphem_rapids.generators.generate_delaunay_triangulation(n=100, seed=0)[source]

Generate a Delaunay triangulation graph.

Vertices are randomly placed in a 2D unit square, and edges are created based on the Delaunay triangulation of these points. The resulting graph has planar structure with triangular faces.

Parameters:

  • n – int Number of vertices.

  • seed – int Random seed for reproducibility.

Returns:

scipy.sparse.csr_matrix

Sparse adjacency matrix (n × n).

Return type:

adjacency