Module layout 

Graph layouts: placing vertices in the plane or in 3D space (igraph_layout.h).

A layout assigns coordinates to every vertex of a graph, typically to draw it. Every layout function of this module returns a Matrix with one row per vertex (row i holds the coordinates of vertex i) and two columns (x, y) for 2D layouts, or three columns (x, y, z) for the *_3d variants. Use Matrix::row, Matrix::column or Matrix::to_rows to read them.

This module binds the whole of the C header igraph_layout.h: simple geometric layouts, force-directed layouts (with tunable options structs whose Default follows the recommendations of the igraph documentation), tree and layered layouts, dimensionality reduction layouts (MDS, UMAP) and a few helpers.

use igraph::prelude::*;
use igraph::layout::FruchtermanReingoldOptions;

// A 6-cycle.
let g = Graph::ring(6, false, false, true).unwrap();

// Deterministic geometric layout: all vertices on the unit circle.
let circle = g.layout_circle(..).unwrap();
assert_eq!(circle.shape(), (6, 2));
for p in circle.rows() {
    assert!((p[0].hypot(p[1]) - 1.0).abs() < 1e-12);
}

// Randomized force-directed layout, made reproducible by seeding the RNG.
let opts = FruchtermanReingoldOptions::default();
rng::seed(42).unwrap();
let fr = g.layout_fruchterman_reingold(&opts).unwrap();
rng::seed(42).unwrap();
assert_eq!(g.layout_fruchterman_reingold(&opts).unwrap(), fr);
assert_eq!(fr.shape(), (6, 2));

Provided functionality

Family	2D	3D
Random	layout_random	layout_random_3d
Regular shapes	layout_circle, layout_star, layout_grid	layout_sphere, layout_grid_3d
Fruchterman–Reingold	layout_fruchterman_reingold	layout_fruchterman_reingold_3d
Kamada–Kawai	layout_kamada_kawai	layout_kamada_kawai_3d
DrL	layout_drl	layout_drl_3d
UMAP	layout_umap, layout_umap_compute_weights	layout_umap_3d
Other force-directed	layout_lgl, layout_graphopt, layout_gem, layout_davidson_harel
Trees	layout_reingold_tilford, layout_reingold_tilford_circular, roots_for_tree_layout
Layered / bipartite	layout_sugiyama, layout_bipartite
Distance based	layout_mds (any dimension)
Helpers	layout_align (any dimension), layout_merge_dla

Starting positions and reproducibility

Iterative layouts (Fruchterman–Reingold, Kamada–Kawai, DrL, UMAP, graphopt, GEM, Davidson–Harel) can start from a given layout: set the initial field of their options (or pass it explicitly) to refine an existing layout, otherwise they start from a random (or, for Kamada–Kawai, circular) configuration. Random choices (random starts, LGL’s random root, GEM’s vertex order, DLA random walks, …) use the calling thread’s default random number generator. Every thread has its own, so rng::seed makes the layouts computed afterwards in that thread reproducible, whatever other threads do. To leave the thread’s default stream untouched, run the layout inside Rng::scoped with a generator of your own:

use igraph::prelude::*;
use igraph::layout::GemOptions;

let g = Graph::ring(4, false, false, true).unwrap();
let run = || Rng::new(RngType::Pcg64, 42).unwrap().scoped(|| g.layout_gem(&GemOptions::default()));
assert_eq!(run().unwrap(), run().unwrap());

See also

• Graphs to lay out: Graph::famous, Graph::ring, Graph::kary_tree, Graph::square_lattice (constructors module).
• Disconnected graphs: Graph::decompose splits a graph into its components, which can be laid out separately and merged with layout_merge_dla.
• Inputs of some layouts: Graph::distances (the default distance matrix of layout_mds), Graph::bipartite_types (the types of layout_bipartite), Graph::feedback_arc_set (how layout_sugiyama breaks cycles), Graph::nearest_neighbor_graph (a typical input of layout_umap).
• Using a layout: Graph::spatial_edge_lengths measures the edges of a drawing, convex_hull_2d its outline, and community detection (e.g. Graph::community_multilevel) gives vertex colors.

Structs

DavidsonHarelOptions

Parameters of the Davidson–Harel layout (Graph::layout_davidson_harel).

FruchtermanReingoldOptions

Parameters of the Fruchterman–Reingold layouts (Graph::layout_fruchterman_reingold and Graph::layout_fruchterman_reingold_3d).

GemOptions

Parameters of the GEM layout (Graph::layout_gem).

GraphoptOptions

Parameters of the graphopt layout (Graph::layout_graphopt).

KamadaKawaiOptions

Parameters of the Kamada–Kawai layouts (Graph::layout_kamada_kawai and Graph::layout_kamada_kawai_3d).

LglOptions

Parameters of the Large Graph Layout (Graph::layout_lgl).

SugiyamaLayout

Result of Graph::layout_sugiyama.

SugiyamaOptions

Parameters of the Sugiyama layered layout (Graph::layout_sugiyama).

UmapOptions

Parameters of the UMAP layouts (Graph::layout_umap and Graph::layout_umap_3d).

Enums

DrlTemplate

Predefined parameter templates for the DrL layout (igraph_layout_drl_default_t), see DrlOptions::from_template.

RootChoice

Heuristic used by Graph::roots_for_tree_layout to choose among several possible roots (igraph_root_choice_t).

Functions

layout_merge_dla

Merges the 2D layouts of several graphs (typically the components of a graph) into one, using diffusion-limited aggregation (DLA).

Type Aliases

DrlOptions

Parameters of the DrL layout (igraph_layout_drl_options_t), used by Graph::layout_drl and Graph::layout_drl_3d.