NDlib: Network Diffusion Simulation in Python

Social phenomena — from viral misinformation to epidemic outbreaks — propagate through networks of human relationships. Understanding how and how fast these processes unfold requires tools that can model both the network topology and the diffusion dynamics simultaneously. NDlib (Network Diffusion Library) is an open-source Python library purpose-built for this challenge, offering a rich catalogue of compartmental and threshold-based diffusion models that run directly on NetworkX graph objects.

What NDlib Does

NDlib, developed at the Knowledge Discovery and Data Mining Laboratory (KDDLab) at the University of Pisa, provides a unified simulation framework for studying spreading processes on complex networks. Rather than forcing analysts to re-implement standard epidemic or opinion models from scratch, NDlib ships with more than 30 ready-to-use models spanning:

Epidemic compartmental models: SIR, SIS, SEIR, SEIRS, SEIS, SWIR, Threshold, and several variants with heterogeneous transmission rates.
Opinion dynamics models: Voter, Sznajd, Cognitive Opinion Dynamics, Algorithmic Bias, and Deffuant-Weisbuch bounded confidence (complementing the standalone Deffuant model).
Multilayer and temporal network support: diffusion across multiplex networks where nodes participate in multiple relationship layers simultaneously.

The library integrates natively with NetworkX, meaning any graph you can construct or import — from empirical contact datasets to synthetic Barabási–Albert or Watts–Strogatz topologies — can serve as the substrate for a simulation run.

Core Workflow

NDlib simulation pipeline architecture

A typical NDlib simulation follows four steps:

1. Build or load the network

import networkx as nx
import ndlib.models.epidemics as ep
from ndlib.models.ModelConfig import Configuration

G = nx.erdos_renyi_graph(10000, 0.01)

2. Instantiate and configure the model

model = ep.SIRModel(G)
cfg = Configuration()
cfg.add_model_parameter('beta', 0.01)   # infection rate
cfg.add_model_parameter('gamma', 0.005) # recovery rate
cfg.add_model_parameter('fraction_infected', 0.05)
model.set_initial_status(cfg)

3. Run iterations

iterations = model.iteration_bunch(200)

4. Analyse and visualise trends

from ndlib.viz.mpl.DiffusionTrend import DiffusionTrend
trends = model.build_trends(iterations)
viz = DiffusionTrend(model, trends)
viz.plot("sir_trend.pdf")

This four-step pattern is consistent across all models, so switching from SIR to SEIR or from an epidemic model to an opinion dynamics model requires only changing the model class and its parameters — the rest of the pipeline stays identical.

Heterogeneous Transmission and Node-Level Parameters

One of NDlib's most practically useful features is support for node- and edge-level parameter heterogeneity. Real social networks are not homogeneous: some individuals are more susceptible, some contacts are stronger than others. NDlib lets analysts assign per-node or per-edge values for any model parameter:

# Assign individual-level susceptibility
for node in G.nodes():
    cfg.add_node_configuration("threshold", node, random.gauss(0.1, 0.02))

This capability is essential for modelling realistic scenarios such as vaccine hesitancy (heterogeneous immunity), targeted interventions (removing high-degree spreaders), or media influence (boosting recovery rates for nodes exposed to counter-messaging).

Comparing Intervention Scenarios

NDlib's DiffusionPrevalence and MultiPlot visualisation utilities make it straightforward to compare multiple simulation runs — for example, a baseline epidemic versus one with a 20 % vaccination campaign:

from ndlib.viz.mpl.MultiPlot import MultiPlot

vm = MultiPlot()
vm.add_plot(trends_baseline)
vm.add_plot(trends_vaccinated)
vm.plot("comparison.pdf")

Because each model instance is independent, analysts can run parameter sweeps in parallel using Python's multiprocessing module or submit batches to an HPC cluster, then aggregate results to compute confidence intervals over stochastic realisations.

Multilayer Network Diffusion

Many real-world spreading processes operate across multiple relationship layers — a disease may spread through both household contacts and workplace contacts, while information spreads through an online social network. NDlib's MultilayerDiffusion module handles this by accepting a list of NetworkX graphs (one per layer) and a coupling matrix that governs cross-layer transitions. This is particularly relevant for modelling co-evolution of disease and awareness, where awareness spreading on a social media layer can suppress disease transmission on a physical contact layer.

NDlib SIR peak prevalence by network topology

Practical Considerations

Scale: NDlib is single-threaded by default. For networks exceeding ~500 k nodes, consider using the ndlib-rest microservice wrapper, which exposes the same API over HTTP and can be deployed on a multi-core server.
Stochasticity: All models are stochastic. Run at least 30–50 independent realisations and report mean ± standard deviation of peak prevalence and time-to-peak.
Network source: Simulation results are highly sensitive to network topology. Always validate against an empirical contact network (e.g., from the SocioPatterns project) before drawing policy conclusions from synthetic graphs.
Temporal networks: Use the TemporalNetwork wrapper to feed time-stamped edge lists; NDlib will activate and deactivate edges according to the contact schedule, capturing the burstiness of real human interaction.

When to Use NDlib

NDlib is the right tool when your research question centres on how network structure shapes diffusion outcomes — not just what the final epidemic size is, but which nodes become infected first, how community structure creates firebreaks, or how seeding strategy affects cascade speed. It is less suited to agent-level behavioural heterogeneity (where Mesa or Agents.jl offer richer agent cognition) or to very large-scale GPU-accelerated runs (where FLAME GPU 2 is more appropriate).

$NDlib Voter Model opinion fraction dynamics on a scale-free network$

Further Resources

GitHub repository: github.com/GiulioRossetti/ndlib
Official documentation: ndlib.readthedocs.io
Companion paper: Rossetti et al., "NDlib: A Python Library to Model Diffusion Processes in Complex Networks," Journal of Machine Learning Research, 2018.
SocioPatterns empirical contact data: sociopatterns.org
NetworkX documentation: networkx.org

NDlib lowers the barrier to rigorous, reproducible diffusion simulation on complex networks. Its consistent API, broad model catalogue, and native NetworkX integration make it a practical first choice for social scientists, epidemiologists, and computational social scientists who need to move quickly from a research question to a validated simulation result.