Skip to main content

​
What is Emergent?

Emergent is a Python framework for building and running agent-based models (ABMs) on graph structures. It lets you define populations of agents that interact through a network, each following custom behaviors you write, and simulate how the system evolves over time until it reaches a steady state. The framework is built on top of NetworkX for graph management and NumPy for numerical operations, giving you a clean, minimal API while leveraging battle-tested scientific computing libraries under the hood.

Quickstart

Install Emergent and run your first simulation in minutes.

AgentModel

Learn how the core AgentModel class works.

Guides

Step-by-step guides for common simulation patterns.

API Reference

Complete reference for every method and parameter.

​
Key features

Graph-based simulations

Model agent networks as complete, cycle, or wheel graphs — or inject any custom NetworkX graph.

Custom behaviors

Define your own initial data and timestep functions as plain Python callables.

Convergence detection

Automatically stop simulations when a tracked variable’s standard deviation falls below a threshold.

Flexible parameters

Store arbitrary simulation parameters on the model and read them inside your behavior functions.

​
How it works

Emergent follows a straightforward lifecycle:
  1. Configure — create an AgentModel, set parameters, and choose a graph topology.
  2. Define behaviors — write an initial_data_function that seeds each node and a timestep_function that updates the model each tick.
  3. Initialize — call initialize_graph() to build the graph and seed all nodes.
  4. Run — call timestep() to advance one step at a time, or run_to_convergence() to let the model drive itself to a stable state.
from emergent.main import AgentModel
import random

model = AgentModel()
model.update_parameters({"num_nodes": 10, "graph_type": "complete"})

def init(m):
    return {"opinion": random.random()}

def step(m):
    graph = m.get_graph()
    for node in graph.nodes():
        neighbors = list(graph.neighbors(node))
        if neighbors:
            neighbor = random.choice(neighbors)
            avg = (graph.nodes[node]["opinion"] + graph.nodes[neighbor]["opinion"]) / 2
            graph.nodes[node]["opinion"] = avg

model.set_initial_data_function(init)
model.set_timestep_function(step)
model.initialize_graph()
model.run_to_convergence()

​
When to use Emergent

Emergent is a good fit when you need to:
  • Model opinion dynamics, disease spread, or information diffusion over a social network
  • Prototype agent-based models quickly without low-level graph wiring
  • Study how network topology (complete vs. cycle vs. wheel) affects emergent behavior
  • Build reproducible simulations in Python using familiar scientific libraries

​
License

Emergent is released under the MIT License.

Build docs developers (and LLMs) love

Get started for freeTalk to us