= Layout

Compute 2D or 3D coordinates for vertices so the graph can be drawn.
Layout algorithms do not change the graph structure; they only produce
positions.

[cols="1,3"]
|===
| Algorithm | When to use

| xref:algorithms/layout/random_layout.adoc[Random Layout]
| Starting point. Assigns random positions. Often used to seed a
  force-directed layout.

| xref:algorithms/layout/circle_layout.adoc[Circle Layout]
| Places vertices evenly on a circle. Good for small graphs or ring
  topologies.

| xref:algorithms/layout/kamada_kawai_spring_layout.adoc[Kamada-Kawai]
| Spring model based on graph-theoretic distances. Produces aesthetically
  pleasing layouts for small to medium graphs (< ~1000 vertices).

| xref:algorithms/layout/fruchterman_reingold.adoc[Fruchterman-Reingold]
| Force-directed. Scales better than Kamada-Kawai. Good for medium graphs.

| xref:algorithms/layout/gursoy_atun_layout.adoc[Gursoy-Atun]
| Topology-based layout using self-organizing maps. Works on arbitrary
  topologies (sphere, torus, etc.).
|===

TIP: For most graphs, start with a random layout and then run
Fruchterman-Reingold or Kamada-Kawai. Kamada-Kawai produces better results
but is slower; Fruchterman-Reingold is faster and handles larger graphs.

All layout algorithms write positions into a property map. The topology
(rectangle, circle, sphere, heart, etc.) is specified via a topology object;
see xref:algorithms/layout/topology.adoc[Topologies for Graph Drawing] for
the catalog of built-in types (`square_topology`, `cube_topology`,
`ball_topology`, `sphere_topology`, `heart_topology`, …) and the concept a
custom topology must model.
