ForceAtlas2

SQL function: cugraph_force_atlas2

Official cuGraph reference: Python API

Place vertices in two dimensions with a force-directed simulation that attracts connected vertices and repels vertices from one another.

Signature

cugraph_force_atlas2(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, Int64	The numeric output schema is used for numeric calls.
Logical string edge endpoints	Utf8, LargeUtf8, Utf8View	Vertex identity columns are canonicalized to Utf8; scores, distances, counts, coordinates, and opaque labels remain numeric.

The native mapping type is Int64. Call-specific output schemas come from gpu_validate_call.

Logical string side-input limitations:

• edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs

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		optional edge weight column for graph construction when supported by the algorithm; semantic effect: edge weights affect algorithm results when provided

JSON options

Option	Type	Default	Constraints	Description
barnes_hut_optimize	Boolean	false
barnes_hut_theta	Float64	0.5	min 0; max 1
edge_weight_influence	Float64	1	min 0
gravity	Float64	1	min 0
jitter_tolerance	Float64	1	min 0
lin_log_mode	Boolean	false
max_iter	UInt32	500	min 1; max 2147483647
outbound_attraction_distribution	Boolean	false
overlap_scaling_ratio	Float64	2	> 0
prevent_overlapping	Boolean	false	one of false; valid when unsupported until vertex_radius side inputs are exposed by the SQL API
scaling_ratio	Float64	2	> 0
seed	UInt64	0
strong_gravity_mode	Boolean	false
verbose	Boolean	false

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|Utf8	no	Vertex receiving ForceAtlas2 layout coordinates.
x	Float32	no	X coordinate assigned by ForceAtlas2.
y	Float32	no	Y coordinate assigned by ForceAtlas2.

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.

Lay out an ego network on the GPU

Three statements build the one-hop neighborhood around Attention Is All You Need (its ~40 references, its 110 most-cited citers, and every citation among them), and ForceAtlas2 returns drawable coordinates. A second call — cugraph_louvain on the same edge view — colors the clusters:

CREATE VIEW attention_ego_nodes AS
SELECT paper_id FROM (
  SELECT dst AS paper_id FROM citation_edges WHERE src = 2963403868
  UNION ALL
  SELECT src AS paper_id FROM (
    SELECT e.src, p.n_citation
    FROM citation_edges_by_dst e JOIN papers p ON p.paper_id = e.src
    WHERE e.dst = 2963403868
    ORDER BY p.n_citation DESC LIMIT 110) t
  UNION ALL
  SELECT 2963403868 AS paper_id
) u GROUP BY paper_id;

CREATE VIEW attention_ego_edges AS
SELECT e.src, e.dst
FROM citation_edges e
JOIN attention_ego_nodes a ON a.paper_id = e.src
JOIN attention_ego_nodes b ON b.paper_id = e.dst;

WITH layout AS (
  SELECT vertex, x, y
  FROM cugraph_force_atlas2('attention_ego_edges', 'src', 'dst', NULL,
                            '{"max_iter":500, "seed":42}')),
community AS (
  SELECT vertex, "partition"
  FROM cugraph_louvain('attention_ego_edges', 'src', 'dst'))
SELECT l.vertex, l.x, l.y, c."partition", p.title, p.year
FROM layout l
JOIN community c ON c.vertex = l.vertex
JOIN papers p ON p.paper_id = l.vertex;

The figure below renders that query's actual output — 133 rows of (vertex, x, y, partition, title, year) — with no client-side layout; the browser draws only what the SQL returned. Louvain's partitions correspond to distinct research threads (labels assigned by inspecting each cluster's members):

seed fixes the initial placement, but the parallel layout itself is not bit-reproducible — expect slightly different (equally valid) coordinates on each run. If downstream queries must agree on positions, snapshot into the mutable datafusion.public workspace with CREATE TABLE … AS; that does not write back to the Iceberg source catalog.

Limitations & lifecycle

• prevent_overlapping=true is rejected until vertex_radius side inputs are exposed

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_force_atlas2',
  '{"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.