Skip to main content
Agents in Emergent live on nodes of a graph, and edges define which agents can interact. The graph_type parameter selects the topology when initialize_graph() builds the graph. Each topology has different connectivity properties that affect how quickly — and whether — a simulation converges.

​
Built-in topologies

​
Complete

Every node is connected to every other node. This is the most densely connected topology. 
from emergent.main import AgentModel

model = AgentModel()
model.update_parameters({
    "num_nodes": 5,
    "graph_type": "complete",
})
model.initialize_graph()
# Each node has 4 neighbors (every other node)
With num_nodes=5 a complete graph has 5 nodes and 10 edges. Every agent has direct access to every other agent’s state each timestep, so influence spreads in a single hop. Simulations on complete graphs typically converge faster than on sparser topologies.
Emergent builds complete graphs with nx.complete_graph(num_nodes) from networkx.

​
Cycle

Nodes are arranged in a ring. Each node is connected only to its two immediate neighbors. 
model = AgentModel()
model.update_parameters({
    "num_nodes": 10,
    "graph_type": "cycle",
})
model.initialize_graph()
# Node 0 — Node 1 — Node 2 — ... — Node 9 — Node 0
With num_nodes=10 a cycle graph has 10 nodes and 10 edges, each of degree 2. Information must travel hop-by-hop around the ring, so convergence is slower than on a complete graph. The cycle topology is useful for modeling localized influence — agents only respond to adjacent neighbors.
Emergent builds cycle graphs with nx.cycle_graph(num_nodes) from networkx.

​
Wheel

One hub node at the center is connected to every outer node. The outer nodes form a ring connected only to their ring neighbors and the hub. 
model = AgentModel()
model.update_parameters({
    "num_nodes": 7,
    "graph_type": "wheel",
})
model.initialize_graph()
# Node 0 is the hub, connected to all of nodes 1-6
# Nodes 1-6 form a cycle among themselves
With num_nodes=7 the wheel graph has 7 nodes: node 0 is the hub with degree 6, and nodes 1–6 each have degree 3 (two ring neighbors plus the hub). The hub acts as a broadcast point — its state reaches all other agents in a single timestep, which can accelerate convergence compared to a pure cycle.
Emergent builds wheel graphs with nx.wheel_graph(num_nodes) from networkx. Note that num_nodes counts the hub, so a wheel with num_nodes=7 has 6 outer nodes.
The wheel topology is a natural fit for simulations with a central authority or broadcaster — for example, a media source influencing a population of listeners who also talk to their neighbors.

​
Custom graphs

You can inject any nx.Graph (or subclass) directly, bypassing the built-in topologies entirely. 
import networkx as nx
from emergent.main import AgentModel

# Use any networkx graph generator
g = nx.barabasi_albert_graph(n=100, m=2)

model = AgentModel()
model.set_graph(g)
model.set_initial_data_function(initial_data)
model.set_timestep_function(timestep)

# initialize_graph() seeds node data but does not rebuild the graph
model.initialize_graph()
set_graph() accepts nx.Graph instances and subclasses. Passing any non-graph value raises Exception: The passed parameter is not a graph object.
Some commonly useful networkx generators:
Produces a power-law degree distribution where a few high-degree hubs dominate connectivity — common in social and technological networks.
g = nx.barabasi_albert_graph(n=200, m=3)
model.set_graph(g)
Each possible edge exists independently with probability p. Good baseline for comparison.
g = nx.erdos_renyi_graph(n=100, p=0.1)
model.set_graph(g)
Combines local clustering with short average path lengths — characteristic of many real social networks.
g = nx.watts_strogatz_graph(n=100, k=4, p=0.1)
model.set_graph(g)
Agents arranged in a 2D lattice. Useful for spatial simulations.
g = nx.grid_2d_graph(10, 10)
# Relabel to integer nodes if your timestep function expects integers
g = nx.convert_node_labels_to_integers(g)
model.set_graph(g)

​
How topology affects propagation

The graph structure determines the neighborhood available to each agent at every timestep. Key effects to consider:
  • Diameter: The longest shortest path between any two nodes. A complete graph has diameter 1 — any two nodes can exchange information in one step. A cycle graph has diameter num_nodes // 2. A larger diameter means slower global propagation.
  • Degree distribution: Uniform degree (complete, cycle) means all agents have identical reach. Non-uniform degree (wheel, scale-free) creates influential hubs whose state propagates faster.
  • Clustering: Highly clustered topologies cause local groups to converge among themselves before reaching a global consensus, which can create long-lasting local equilibria.
If your simulation converges too slowly, try switching from "cycle" to "complete" or using a Barabási–Albert graph with a few high-degree hubs. If you want to study the effect of topology itself, run the same simulation across multiple graph types and compare the timestep counts returned by run_to_convergence().
See Convergence for how to measure and control when a simulation stops, and Parameters for how to set num_nodes and graph_type on the model.

Build docs developers (and LLMs) love

Get started for freeTalk to us