A Python module for building and running agent-based models on networks. Emergent provides an AgentModel that combines a configurable graph topology (via NetworkX) with pluggable initial-data and timestep logic, so you can define custom agent behavior while the framework handles parameters, graph creation, and iteration.
- Python >= 3.10.7
- NetworkX >= 3.3
- NumPy >= 2.0.0
- Matplotlib >= 3.9.2
- SciPy >= 1.15.1
Install from PyPI:
python3 -m pip install emergentOr install from source in development mode:
git clone https://github.com/toni-akintola/modelpy-module.git
cd modelpy-module
pip install -e .from emergent.main import AgentModel, genInitialData, genTimestepData
# Create a model and set parameters
model = AgentModel()
model.update_parameters({
"num_nodes": 5,
"graph_type": "complete",
})
# Plug in your initial data and timestep logic
model.set_initial_data_function(genInitialData)
model.set_timestep_function(genTimestepData)
# Build the graph and run
model.initialize_graph()
model.timestep() # run one step
# or
model.run_to_convergence() # run until MAX_TIMESTEPSThe main class that holds parameters, the graph, and the functions used to initialize and update nodes.
| Parameter | Default | Description |
|---|---|---|
num_nodes |
3 |
Number of nodes in the graph |
graph_type |
"complete" |
Topology: see Graph types |
model_variation |
"base" |
Model variant label |
Use update_parameters(dict) to set these and any custom parameters. Use list_parameters() to see current keys and delete_parameters(list) to remove optional ones.
complete— complete graph (every pair of nodes connected)cycle— cycle graphwheel— wheel graph- Other — empty graph with
num_nodesnodes (custom topologies can be set viaset_graph())
-
set_initial_data_function(callable)
Sets the function used to generate initial node data. It will be called asf(model)once per node; it should return a dict of attributes for that node. -
set_timestep_function(callable)
Sets the function that runs each timestep. It is called asf(model)and should read/update the graph viamodel.get_graph()andmodel.set_graph(). -
initialize_graph()
Creates the graph fromnum_nodesandgraph_type, then assigns initial data to each node using the initial-data function. -
timestep()
Runs one timestep by calling the timestep function. -
run_to_convergence()
Callstimestep()repeatedly up toMAX_TIMESTEPS(1000) and returns the number of steps run. -
get_graph()
Returns the current NetworkX graph (e.g. for inspection or custom layout). -
set_graph(graph)
Replaces the model’s graph with a NetworkX graph (e.g. for custom or external topologies).
-
genInitialData(model)
Example initial-data function: returns a dict with a single"id"key (random int 1–100). -
genTimestepData(model, nodeData)
Example timestep logic: incrementsnodeData["id"]by 1 and returns it.
These are minimal examples; in practice you replace them with your own initial data and timestep logic.
-
Initial data
Implement a function(model: AgentModel) -> dictthat returns the attribute dict for one node. The framework calls it once per node duringinitialize_graph(). -
Timestep
Implement a function(model: AgentModel) -> Nonethat:- Gets the graph with
model.get_graph() - Reads/updates nodes (and optionally edges)
- Calls
model.set_graph(graph)if you replace the graph
- Gets the graph with
-
Custom parameters
Add any keys you need viaupdate_parameters(). Read them in your functions withmodel["param_name"]. -
Custom graph
Build a NetworkX graph yourself and pass it toset_graph()instead of (or after) usinginitialize_graph().
From the project root:
python -m pytest tests/
# or
python -m unittest tests/test.pyBuild the package:
pip install build twine
python -m buildUpload to TestPyPI or PyPI:
twine upload --repository testpypi dist/*
# or
twine upload dist/*See the repository for license information.