NDlib - Network Diffusion Library

NDlib provides implementations of several spreading and opinion dynamics models.

The project documentation can be found on ReadTheDocs.

If you use NDlib as support to your research consider citing:

G. Rossetti, L. Milli, S. Rinzivillo, A. Sirbu, D. Pedreschi, F. Giannotti. NDlib: a Python Library to Model and Analyze Diffusion Processes Over Complex Networks. Journal of Data Science and Analytics. 2017. DOI:0.1007/s41060-017-0086-6 (pre-print available on arXiv)

G. Rossetti, L. Milli, S. Rinzivillo, A. Sirbu, D. Pedreschi, F. Giannotti. "NDlib: Studying Network Diffusion Dynamics", IEEE International Conference on Data Science and Advanced Analytics, DSAA. 2017.

Promo Video

Installation

To install the library just download (or clone) the current project and copy the ndlib folder in the root of your application.

Alternatively use pip:

sudo pip install ndlib

Interactive Dashboard

NDlib includes a browser-based dashboard service for quick, code-free experimentation with diffusion and opinion models.

The dashboard lets you:

• build or load a network
• configure model and graph parameters from the UI
• run simulations in a strict three-step workflow
• inspect network state, trends, prevalence, and opinion evolution
• select infected seeds directly from the graph preview for epidemic models
• use community-aware layouts to expose modular structure
• separate the visual model builder into epidemic, continuous-opinion, discrete-opinion, and coupled use cases
• load starter templates such as SIR, Algorithmic Bias, Majority Rule, and a coupled starter layout
• copy the generated NDQL script or download the generated Python class after saving a custom pipeline
• build opinion-only custom models without an Infected class when the selected use case does not require one

Run it from the repository root with:

python ndlib/dashboard/server.py

If the package is installed, you can also launch it with the bundled command:

ndlib-dashboard

Once the server starts, open the local URL printed in the terminal.

Configuration view	Network view

Visual Model Builder

NDlib includes an interactive Visual Model Builder that allows designing custom compartmental models by drag-and-drop using a node-graph workflow. Visual models are compiled to standard Python classes and NDQL (Network Diffusion Query Language) scripts, and can be simulated or deleted directly from the dashboard.

The builder now starts from a use-case selector:

• Epidemics: discrete compartmental models with infection, threshold, and attribute-driven rules.
• Continuous Opinions: numeric-opinion layouts centered on numerical checks and continuous-variable style routing.
• Discrete Opinions: label-based opinion layouts with categorical and stochastic influence blocks.
• Coupled / Advanced: a mixed workspace that exposes every block for richer custom experiments.

Custom opinion starters now initialize their own statuses directly, so they no longer inherit the epidemic-only Infected requirement from the base diffusion model.

Starter templates are provided for the most common layouts, so you can begin from a working example instead of a blank canvas.

Draggable building blocks include:

• Status Node: Declares compartmental states (e.g., Susceptible, Infected, Recovered).
• Node Stochastic: Propagates state change stochastically if neighbors match a status.
• Node Threshold: Implements fraction-based cascading activation.
• Edge Stochastic: Evaluates link-level propagation conditions.
• Count Down: Implements fixed iteration-based delays (e.g., recovery after $D$ ticks).
• Node Categorical Attribute: Checks categorical node properties (e.g., gender, city).
• Node Numerical Attribute: Performs numerical checks on node variables (e.g., age ranges).
• Node Numerical Variable: Compares numeric opinion-like values or attributes against a threshold.
• Conditional Composition: Composes decision logic gates by nesting condition, if-true, and if-false branches.

Use-case-aware Builder

The sidebar also includes:

• a live NDQL preview with a one-click copy action
• a per-model download button for the generated Python source
• example templates that can populate the canvas with a starter layout

See the full builder guide in docs/visual_model_builder_opinion_epidemic_guide.md.

Documentation, Tutorials and Online Environments

For examples, tutorials and a complete reference visit the project documentation website on ReadTheDocs.

If you would like to test NDlib functionalities without installing anything on your machine consider using the preconfigured Jupyter Hub instances offered by SoBigData RI.

Jupyter Notebook Tutorial

Interested in an extensive tutorial on NDlib? Check out the official Jupyter Notebooks!

NDlib Overview

Collaborate with us!

NDlib is an active project, any contribution is welcome!

If you like to include your model in NDlib feel free to fork the project, open an issue and contact us.

How to contribute to this project?

Contributing is good, doing it correctly is better! Check out our rules, issue a proper pull request /bug report / feature request.

Do you want to be part of the NDlib community to discuss enhancements, desiderata, bug fix? Join us on Slack!

We are a welcoming community... just follow the Code of Conduct.