Quickstart

Install Emergent

pip install emergent

Build your first simulation

A simulation in Emergent has four steps:

Create an AgentModel
Define an initial data function — what state does each agent start with?
Define a timestep function — how does each agent update?
Run the simulation

Step 1 — Create the model

from emergent import AgentModel

model = AgentModel()

By default this creates a model with 3 nodes on a complete graph. You can customize both:

model.update_parameters({
    "num_nodes": 10,
    "graph_type": "cycle",
})

Step 2 — Define the initial data function

Each node receives the return value of this function as its starting data. The function receives the model as its only argument.

import random

def initial_data(model):
    return {"opinion": random.uniform(0, 1)}

model.set_initial_data_function(initial_data)

Step 3 — Define the timestep function

This function is called once per timestep and should mutate node data on the graph. Use model.get_graph() to access the underlying NetworkX graph.

import networkx as nx

def timestep(model):
    graph = model.get_graph()
    for node in graph.nodes():
        neighbors = list(graph.neighbors(node))
        if not neighbors:
            continue
        neighbor_opinions = [graph.nodes[n]["opinion"] for n in neighbors]
        # Move each agent's opinion toward the average of its neighbors
        avg = sum(neighbor_opinions) / len(neighbor_opinions)
        graph.nodes[node]["opinion"] = (graph.nodes[node]["opinion"] + avg) / 2

model.set_timestep_function(timestep)

Step 4 — Run the simulation

Option A — Run to convergence Emergent can automatically stop when a tracked variable stabilizes within a given standard deviation threshold:

model.update_parameters({
    "convergence_data_key": "opinion",
    "convergence_std_dev": 0.01,
})

model.initialize_graph()
timestep_count = model.run_to_convergence()
print(f"Converged after {timestep_count} timesteps")

Option B — Run a fixed number of steps

model.initialize_graph()
for _ in range(50):
    model.timestep()

Complete example

import random
import networkx as nx
from emergent import AgentModel

def initial_data(model):
    return {"opinion": random.uniform(0, 1)}

def timestep(model):
    graph = model.get_graph()
    for node in graph.nodes():
        neighbors = list(graph.neighbors(node))
        if not neighbors:
            continue
        avg = sum(graph.nodes[n]["opinion"] for n in neighbors) / len(neighbors)
        graph.nodes[node]["opinion"] = (graph.nodes[node]["opinion"] + avg) / 2

model = AgentModel()
model.update_parameters({
    "num_nodes": 20,
    "graph_type": "complete",
    "convergence_data_key": "opinion",
    "convergence_std_dev": 0.01,
})
model.set_initial_data_function(initial_data)
model.set_timestep_function(timestep)
model.initialize_graph()

steps = model.run_to_convergence()
print(f"Converged in {steps} steps")

Get Started

Core Concepts

Examples

Install Emergent

Build your first simulation

Step 1 — Create the model

Step 2 — Define the initial data function

Step 3 — Define the timestep function

Step 4 — Run the simulation

Complete example

Next steps

AgentModel concepts

Graph structures

​Install Emergent

​Build your first simulation

​Step 1 — Create the model

​Step 2 — Define the initial data function

​Step 3 — Define the timestep function

​Step 4 — Run the simulation

​Complete example

​Next steps

AgentModel concepts

Graph structures

Install Emergent

Build your first simulation

Step 1 — Create the model

Step 2 — Define the initial data function

Step 3 — Define the timestep function

Step 4 — Run the simulation

Complete example

Next steps