Skip to main content

Continuous-time Noisy Voter Model (CNVM) of social dynamics.

Project description

build

Continuous-time noisy voter model (CNVM)

This package provides an efficient implementation of the CNVM, which is a dynamical system consisting a network of interacting agents. It can be used to simulate how opinions about certain issues develop over time within a population, or how an infectious disease spreads. Although the interaction rules of the CNVM are quite simple, the resulting dynamics is complex and rich. There are numerous papers studying the behavior of the CNVM or similar voter models. In this package the simulation loop is just-in-time compiled using numba, which makes performance comparable with languages like C++.

Installation

The CNVM package requires Python 3.9 or 3.10. Install from the PyPI repository:

pip install cnvm

or get the latest version directly from GitHub:

pip install git+https://github.com/lueckem/cnvm

About the CNVM

Let a network (undirected simple graph) of $N$ nodes be given. The nodes represent agents and the edges social interactions. Each node is endowed with one of $M$ discrete opinions. Thus, the system state is given by a vector $x \in {1,\dots,M}^N$, where $x_i$ describes the opinion of node $i$. Each node's opinion $x_i \in {1,\dots,M}$ changes over time according to a continuous-time Markov chain (Markov jump process). Given the current system state $x$, the generator matrix $Q^i$ of the continuous-time Markov chain associated with node $i$ is defined as

$$ Q^i \in \mathbb{R}^{M \times M},\quad (Q^i)_ {m,n} := r_{m,n} \frac{d_ {i,n}(x)}{(d_i)^\alpha} + \tilde{r}_ {m,n},\ m\neq n, $$

where $d_{i,n}(x)$ denotes the number of neighbors of node $i$ with opinion $n$ and $d_i$ is the degree of node $i$. The matrices $r, \tilde{r} \in \mathbb{R}^{M \times M}$ and $\alpha \in \mathbb{R}$ are model parameters.

Thus, the transition rates $(Q^i)_ {m,n}$ consist of two components. The first component $r_{m,n} d_{i,n}(x)/ (d_i)^\alpha$ describes at which rate node $i$ gets "infected" with opinion $n$ by nodes in its neighborhood. The second part $\tilde{r}_{m,n}$ describes transitions that are independent from the neighborhood (e.g., noise).

The parameter $\alpha$ can be used to tune the type of interaction. For $\alpha=1$ the transition rates are normalized because $d_{i,n}(x)/d_i \in [0,1]$. The setting $\alpha=0$ however yields a linear increase of the transition rates with the number of "infected" neighbors, and is often used in epidemic modeling, e.g., the contact process or SIS model.

In the CNVM the network itself is static, i.e., the nodes and edges do not change over time.

Basic Usage

First define the model paramaters:

from cnvm import Parameters
import numpy as np
import networkx as nx

num_nodes = 100
r = np.array([[0, .8], [.2, 0]])
r_tilde = np.array([[0, .1], [.2, 0]])
network = nx.erdos_renyi_graph(n=num_nodes, p=0.1)

params = Parameters(
    num_opinions=2,
    network=network,
    r=r,
    r_tilde=r_tilde,
    alpha=1,
)

Then simulate the model, starting in state x_init:

from cnvm import CNVM

x_init = np.random.randint(0, 2, num_nodes)
model = CNVM(params)
t, x = model.simulate(t_max=50, x_init=x_init)

The output t contains the time points of state jumps and x the system states after each jump.

A more detailed overview of the package can be found in the jupyter notebook examples/tutorial.ipynb. Moreover, the behavior of the CNVM in the mean-field limit is discussed in examples/mean_field.ipynb. In the notebook examples/SIS-model.ipynb the existence of an epidemic threshold for the SIS model in epidemiology is demonstrated.

Implementation details

After a node switches its opinion, the system state $x$ changes and hence all the generator matrices $Q^i$ may change as well. We apply a Gillespie-like algorithm to generate statistically correct samples of the process. We start a Poisson clock for each possible transition and as soon as the first transition occurs we modify the generator matrices and reset all the clocks. To do this efficiently, it is advantageous to transform the rate matrices $r$ and $\tilde{r}$ into an equivalent format consisting of base rates $r_0, \tilde{r}_0 > 0$ and probability matrices $p, \tilde{p} \in [0, 1]^{M\times M}$ such that

$$ r_{m,n} = r_0 p_ {m,n}, \quad \tilde{r}_ {m,n} = \tilde{r}_ 0 \tilde{p}_ {m,n} / M. $$

Furthermore, we define the cumulative rates

$$ \lambda := \sum_{i=1}^N r_0 d_i^{(1-\alpha)},\quad \tilde{\lambda} := N \tilde{r}_0,\quad \hat{\lambda} := \lambda + \tilde{\lambda}. $$

Then the simulation loop is given by

  1. Draw time of next jump event from exponential distribution $\exp(\hat{\lambda})$. Go to 2.
  2. With probability $\lambda / \hat{\lambda}$ the event is due to infection, in which case go to 3. Else it is due to noise, go to 4.
  3. Draw agent $i$ from ${1,\dots,N}$ according to distribution $\mathbb{P}(i = j) = r_0 d_j^{(1-\alpha)} / \lambda$. Let $m$ denote the state of agent $i$. Draw $n$ from ${1,\dots,M}$ according to $\mathbb{P}(n = k) = d_{i,k}(x) / d_i$. With probability $p_{m,n}$ agent $i$ switches to state $n$. Go back to 1.
  4. Draw $i$ from ${1,\dots,N}$ and $n$ from ${1,\dots,M}$ uniformly. Let $m$ denote the state of agent $i$. With probability $\tilde{p}_{m,n}$ agent $i$ switches to state $n$. Go back to 1.

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

cnvm-0.2.0.tar.gz (26.5 kB view details)

Uploaded Source

Built Distribution

cnvm-0.2.0-py3-none-any.whl (28.9 kB view details)

Uploaded Python 3

File details

Details for the file cnvm-0.2.0.tar.gz.

File metadata

  • Download URL: cnvm-0.2.0.tar.gz
  • Upload date:
  • Size: 26.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.4.2 CPython/3.9.13 Windows/10

File hashes

Hashes for cnvm-0.2.0.tar.gz
Algorithm Hash digest
SHA256 56160ebfd7e2ddaeb46b7cce223b6b1e9f1291677725325410918386421313e6
MD5 53a2c74d73dbbfb4b11e1c3c120bf46e
BLAKE2b-256 52e9be6e81ec18096a625e9e9fb58afa0cf410b10d175e5c29cc10f33510b127

See more details on using hashes here.

File details

Details for the file cnvm-0.2.0-py3-none-any.whl.

File metadata

  • Download URL: cnvm-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 28.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.4.2 CPython/3.9.13 Windows/10

File hashes

Hashes for cnvm-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 4a8f14743311a4a646e82a5c50759334e87a66d6e946073d1d06dfee864d27d3
MD5 6ce47c1b1a509cde6b61b965ce5fc625
BLAKE2b-256 d651cbc72b5f71bc2028570e7d4bed7df2b339bf76e5cdbe2522a4dfebe37aed

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