Skip to main content

Network Diffusion - a package for simulating spreading phenomena.

Project description

Network Diffusion - Spreading Models in Networks

Licence PyPI version

Tests Builds Docs Codecov FOSSA Status

This Python library provides a versatile toolkit for simulating diffusion processes in complex networks. It offers support for various types of models, including temporal models, multilayer models, and combinations of both.

Short Example

import network_diffusion as nd

# define the model with its internal parameters
spreading_model = nd.models.MICModel(
    seeding_budget=[90, 10, 0],  # 95% act suspected, 10% infected, 0% recovered
    seed_selector=nd.seeding.RandomSeedSelector(),  # pick infected act randomly
    protocol="OR",  # how to aggregate impulses from the network's layers
    probability=0.5,  # probability of infection
)

# get the graph - a medium for spreading
network = nd.mln.functions.get_toy_network_piotr()

# perform the simulation that lasts four epochs
simulator = nd.Simulator(model=spreading_model, network=network)
logs = simulator.perform_propagation(n_epochs=3)

# obtain detailed logs for each actor in the form of JSON
raw_logs_json = logs.get_detailed_logs()

# or obtain aggregated logs for each of the network's layer
aggregated_logs_json = logs.get_aggragated_logs()

# or just save a summary of the experiment with all the experiment's details
logs.report(visualisation=True, path="my_experiment")

Key Features

  • Complex Network Simulation: The library enables users to simulate diffusion processes in complex networks with ease. Whether you are studying information spread, disease propagation, or any other diffusion phenomena, this library has you covered.

  • Temporal Models: You can work with temporal models, allowing you to capture the dynamics of processes over time. These temporal models can be created using regular time windows or leverage CogSnet.

  • Multilayer Networks: The library supports multilayer networks, which are essential for modelling real-world systems with interconnected layers of complexity.

  • Predefined Models: You have the option to use predefined diffusion models such as the Linear Threshold Model, Independent Cascade Model, and more. These models simplify the simulation process, allowing you to focus on your specific research questions.

  • Custom Models: Additionally, Network Diffusion allows you to define your own diffusion models using open interfaces, providing flexibility for researchers to tailor simulations to their unique requirements.

  • Centrality Measures: The library provides a wide range of centrality measures specifically designed for multilayer networks. These measures can be valuable for selecting influential seed nodes in diffusion processes.

  • NetworkX Compatible: The package is built on top of NetworkX, ensuring seamless compatibility with this popular Python library for network analysis. You can easily integrate it into your existing NetworkX-based workflows.

  • PyTorch representation: Network Diffusion offers a plausible converter of the multilayer network to PyTorch sparse representation. That feature can help in deep-learning experiments utilising complex networks (e.g. GNNs).

Package Installation

To install the package, run this command: pip install network_diffusion. Please note that we currently support Linux, MacOS, and Windows, but the package is mostly tested and developed on Unix-based systems.

To contribute, please clone the repo, switch to a new feature branch, and install the environment:

conda env create -f env/conda.yml
conda activate network-diffusion
pip install -e .

Documentation

Reference guide is available here!

Please bear in mind that this project is still in development, so the API usually differs between versions. Nonetheless, the code is documented well, so we encourage users to explore the repository. Another way to familiarise yourself with the operating principles of network_diffusion are projects which utilise it:

  • Generator of a dataset with actors' spreading potentials - v0.16.0 - repo
  • Influence max. under LTM in multilayer networks - v0.14.0 pre-release - repo
  • Comparison of spreading in various temporal network models - v0.13.0 - repo
  • Seed selection methods for ICM in multilayer networks - v0.10.0 - repo
  • Modelling coexisting spreading phenomena - v0.6 - repo

Citing the Library

If you used the package, please consider citing us:

@article{czuba2024networkdiffusion,
  title={Network Diffusion Framework to Simulate Spreading Processes in Complex Networks},
  author={
      Czuba, Micha{\l} and Nurek, Mateusz and Serwata, Damian and Qi, Yu-Xuan
      and Jia, Mingshan and Musial, Katarzyna and Michalski, Rados{\l}aw
      and Br{\'o}dka, Piotr
    },
  journal={Big Data Mining And Analytics},
  volume={7},
  number={3},
  pages={637-654},
  year={2024},
  publisher={IEEE},
  doi = {10.26599/BDMA.2024.9020010},
  url={https://doi.org/10.26599/BDMA.2024.9020010},
}

Particularly if you used the functionality of simulating coexisting phenomena in complex networks, please add the following reference:

@inproceedings{czuba2022coexisting,
  author={Czuba, Micha\l{} and Br\'{o}dka, Piotr},
  booktitle={9th International Conference on Data Science and Advanced Analytics (DSAA)},
  title={Simulating Spreading of Multiple Interacting Processes in Complex Networks},
  volume={},
  number={},
  pages={1-10},
  year={2022},
  month={oct},
  publisher={IEEE},
  address={Shenzhen, China},
  doi={10.1109/DSAA54385.2022.10032425},
  url={https://ieeexplore.ieee.org/abstract/document/10032425},
}

Reporting Bugs

Please report bugs on this board or by sending a direct e-mail to the main author.

About Us

This library is developed and maintained by Network Science Lab from Politechnika Wrocławska / Wrocław University of Science and Technology / Technische Universität Breslau and external partners. For more information and updates, please visit our website or GitHub page.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Built Distributions

network_diffusion-0.17.0rc20241023094012-cp312-cp312-win_amd64.whl (129.6 kB view details)

Uploaded CPython 3.12 Windows x86-64

network_diffusion-0.17.0rc20241023094012-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.whl (145.2 kB view details)

Uploaded CPython 3.12 manylinux: glibc 2.5+ x86-64

network_diffusion-0.17.0rc20241023094012-cp312-cp312-macosx_10_13_universal2.whl (132.3 kB view details)

Uploaded CPython 3.12 macOS 10.13+ universal2 (ARM64, x86-64)

File details

Details for the file network_diffusion-0.17.0rc20241023094012.tar.gz.

File metadata

File hashes

Hashes for network_diffusion-0.17.0rc20241023094012.tar.gz
Algorithm Hash digest
SHA256 f1c7aad99de52ba7cfc17ae25e073972745aac64f4ef0d26277d907f35c22c89
MD5 740f18b0a3d01dbe1696ab40f5c449ba
BLAKE2b-256 fee9b7942f3eb424c02ae2089e794efe27843b2a4389daddcca162bfde766263

See more details on using hashes here.

File details

Details for the file network_diffusion-0.17.0rc20241023094012-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for network_diffusion-0.17.0rc20241023094012-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 4e987510d6861633aee0de57a8ee0cf99008f4f6f2c3311db91628d47e49e254
MD5 03173f837742ffd02244f4251eafed09
BLAKE2b-256 82c4014fcc697af86d0562d7ec84a3f4898e12cdc8570223d9f9aded8cfeff93

See more details on using hashes here.

File details

Details for the file network_diffusion-0.17.0rc20241023094012-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.whl.

File metadata

File hashes

Hashes for network_diffusion-0.17.0rc20241023094012-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 125d652aa76294f7d37ca25e9ab49676b8554e6cb345448c647178c0a3ee9622
MD5 bb6c4cd55f88f406fcd5e4b47aff556d
BLAKE2b-256 fe5dcc53e78984b0a7d52169ea56251a9fef73b72583f6bc475de6e0586b6f4d

See more details on using hashes here.

File details

Details for the file network_diffusion-0.17.0rc20241023094012-cp312-cp312-macosx_10_13_universal2.whl.

File metadata

File hashes

Hashes for network_diffusion-0.17.0rc20241023094012-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 7ec356e7e7fdad26126f8ab5e673cf71526c022ea5e5e86de36c70e2bd1ad7b6
MD5 a6a8226e428e0cf1f00aa9b8ff109604
BLAKE2b-256 8e635998aeb8c9285f5e63f2209744990c4cd6f94b53900968bba14d18acf630

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page