Quick Start

This guide will help you create your first graph visualization with egraph in just a few minutes.

Your First Graph Layout

Here’s a minimal example that creates a simple graph and applies a layout algorithm:

import egraph as eg

# Create a simple graph with 5 nodes
graph = eg.Graph()

# Add nodes
n0 = graph.add_node(0)
n1 = graph.add_node(1)
n2 = graph.add_node(2)
n3 = graph.add_node(3)
n4 = graph.add_node(4)

# Add edges to form a simple network
graph.add_edge(n0, n1, (0, 1))
graph.add_edge(n1, n2, (1, 2))
graph.add_edge(n2, n3, (2, 3))
graph.add_edge(n3, n4, (3, 4))
graph.add_edge(n4, n0, (4, 0))

# Create an initial 2D drawing with random positions
drawing = eg.DrawingEuclidean2d.initial_placement(graph)

# Apply Stress Majorization layout algorithm
sm = eg.StressMajorization(graph, drawing, lambda _: 100)
sm.run(drawing)

# Get the final positions
positions = {i: (drawing.x(i), drawing.y(i)) for i in range(5)}
# print("Node positions:", positions)

This example:

  1. Creates a graph with 5 nodes

  2. Connects them in a pentagon shape

  3. Initializes random positions for the nodes

  4. Applies the Stress Majorization algorithm to optimize the layout

  5. Extracts the final node positions

Working with NetworkX

egraph integrates seamlessly with NetworkX, a popular Python graph library:

import networkx as nx
import egraph as eg
import matplotlib.pyplot as plt

# Create a graph using NetworkX
nx_graph = nx.karate_club_graph()

# Convert to egraph format
graph = eg.Graph()
indices = {}
for node in nx_graph.nodes:
    indices[node] = graph.add_node(node)
for u, v in nx_graph.edges:
    graph.add_edge(indices[u], indices[v], (u, v))

# Create initial drawing
drawing = eg.DrawingEuclidean2d.initial_placement(graph)

# Apply layout algorithm
sm = eg.StressMajorization(graph, drawing, lambda _: 100)
sm.run(drawing)

# Extract positions for NetworkX visualization
pos = {node: (drawing.x(idx), drawing.y(idx))
       for node, idx in indices.items()}

# Visualize with matplotlib
nx.draw(nx_graph, pos, with_labels=True, node_color='lightblue',
        node_size=500, font_size=10)
# plt.savefig('karate_club.png')
# plt.show()

Using Different Layout Algorithms

egraph provides several layout algorithms. Here’s how to use SGD (Stochastic Gradient Descent):

import egraph as eg

# Create a graph (same as before)
graph = eg.Graph()
indices = [graph.add_node(i) for i in range(5)]
graph.add_edge(indices[0], indices[1], (0, 1))
graph.add_edge(indices[1], indices[2], (1, 2))
graph.add_edge(indices[2], indices[3], (2, 3))
graph.add_edge(indices[3], indices[4], (3, 4))
graph.add_edge(indices[4], indices[0], (4, 0))

# Create initial drawing
drawing = eg.DrawingEuclidean2d.initial_placement(graph)

# Create random number generator for reproducibility
rng = eg.Rng.seed_from(42)

# Use SGD layout algorithm
sgd = eg.FullSgd().build(graph, lambda _: 1.0)

# Create a scheduler to control the optimization process
scheduler = sgd.scheduler(100, 0.1)  # 100 iterations

# Define the optimization step
def step(eta):
    sgd.shuffle(rng)
    sgd.apply(drawing, eta)

# Run the optimization
scheduler.run(step)

# Get final positions
positions = {i: (drawing.x(i), drawing.y(i)) for i in range(5)}
# print("Final positions:", positions)

Key Concepts

Graph: The data structure representing nodes and edges

Drawing: Stores the positions of nodes in a specific geometric space (Euclidean, Hyperbolic, Spherical, or Torus)

Layout Algorithm: Optimizes node positions to create an aesthetically pleasing visualization

Scheduler: Controls the optimization process for iterative algorithms like SGD

Next Steps

Now that you’ve created your first graph layout, explore:

  • Overview - Learn more about egraph’s features and capabilities

  • Graph Basics - Deep dive into graph creation and manipulation

  • Examples - See more examples of different layout algorithms