Dynamics¶

Dynamics classes allow the user to run simulations over a network.

Base class¶

class netrd.dynamics.BaseDynamics[source]¶

Base class for all dynamics processes.

The basic usage is as follows:

>>> ground_truth = nx.read_edgelist("ground_truth.txt")
>>> dynamics_model = Dynamics()
>>> synthetic_TS = dynamics_model.simulate(ground_truth, <some_params>)
>>> # G = Reconstructor().fit(synthetic_TS)

This produces a numpy array of time series data.

Available dynamics¶

All of the following dynamics inherit from BaseDynamics and have the same general usage as above.

`netrd.dynamics.BranchingModel`	A sand-pile-like branching process.
`netrd.dynamics.IsingGlauber`	Ising-Glauber model.
`netrd.dynamics.Kuramoto`	Kuramoto model of oscillators.
`netrd.dynamics.LotkaVolterra`	Lotka-Volterra dynamics of species abundance.
`netrd.dynamics.SISModel`	Susceptible-Infected-Susceptible dynamical process.
`netrd.dynamics.SherringtonKirkpatrickIsing`	Ising model-like dynamics.
`netrd.dynamics.SingleUnbiasedRandomWalker`	Random walk dynamics.
`netrd.dynamics.VoterModel`	Voter dynamics.

Reference¶

class netrd.dynamics.SherringtonKirkpatrickIsing[source]¶

Ising model-like dynamics.

simulate(G, L, noisy=False)[source]¶

Simulate Kinetic Ising model dynamics on a ground truth network.

The results dictionary also stores the ground truth network as ‘ground_truth’.

Parameters

G (nx.Graph): The input (ground-truth) graph with \(N\) nodes.
L (int): The length of the desired time series.

Returns

TS (np.ndarray): An \(N \times L\) array of synthetic time series data.

References

1: D. Sherrington and S. Kirkpatrick, Phys. Rev. Lett. 35, 1792 (1975).
2: Hoang, D.T., Song, J., Periwal, V. and Jo, J., Network inference in stochastic systems from neurons to currencies: Improved performance at small sample size. (2019)

Examples

G = nx.ring_of_cliques(4,16)
L = 2001
dynamics = SherringtonKirkpatrickIsing()
TS = dynamics.simulate(G, L)

class netrd.dynamics.SingleUnbiasedRandomWalker[source]¶

Random walk dynamics.

simulate(G, L, initial_node=None)[source]¶

Simulate single random-walker dynamics on a ground truth network.

Generates an \(N \times L\) time series TS with TS[j,t]==1 if the walker is at node \(j\) at time \(t\), and TS[j,t]==0 otherwise.

The results dictionary also stores the ground truth network as ‘ground_truth’.

Parameters

G (nx.Graph): The input (ground-truth) graph with \(N\) nodes.
L (int): The length of the desired time series.

Returns

TS (np.ndarray): An \(N \times L\) array of synthetic time series data.

Examples

G = nx.ring_of_cliques(4,16)
L = 2001
dynamics = SingleUnbiasedRandomWalker()
TS = dynamics.simulate(G, L)

class netrd.dynamics.Kuramoto[source]¶

Kuramoto model of oscillators.

simulate(G, L, dt=0.01, strength=1, phases=None, freqs=None)[source]¶

Simulate Kuramoto model on a ground truth network.

Kuramoto oscillators model synchronization processes. At each time step, each node adjusts its phase \(\theta_i\) according to the equation

\[\theta_i = \omega_i + \frac{\lambda}{N}\sum_{j=1}^{N}\sin\left(\theta_j - \theta_i\right),\]

where \(\lambda\), is a coupling strength parameter and each node has an internal frequency \(\omega_i\); the freqs function parameter provides the option to initialize these frequencies with user-defined values (or leave as None to randomly initialize). Each node’s initial phase \(\theta_{i0}\) can be randomly initialized (the default behavior) or set by specifying the phases parameter.

The results dictionary also stores the ground truth network as ‘ground_truth’ and the internal frequencies of the process as ‘internal_frequencies’.

For more information on the Kuramoto model, see the review essay included below.

Parameters

G (nx.Graph): the input (ground-truth) graph with \(N\) nodes.
L (int): the length of the desired time series.
dt (float): size of timestep for numerical integration.
strength (float): coupling strength (prefactor for interaction terms).
phases (np.ndarray): an \(N \times 1\) array of initial phases.
freqs (np.ndarray): an \(N \times 1\) array of internal frequencies.

Returns

TS (np.ndarray): an \(N \times L\) array of synthetic time series data.

References

1: F. Rodrigues, T. Peron, P. Ji, J. Kurths. The Kuramoto model in complex networks. https://arxiv.org/abs/1511.07139

Examples

G = nx.ring_of_cliques(4,16)
N = G.number_of_nodes()
L = int(1e4)
omega = np.random.uniform(0.95, 1.05, N)
dynamics = Kuramoto()
TS = dynamics.simulate(G, L, dt=0.01, strength=0.3, freqs=omega)

class netrd.dynamics.LotkaVolterra[source]¶

Lotka-Volterra dynamics of species abundance.

simulate(G, L, init=None, gr=None, cap=None, inter=None, dt=0.01, stochastic=True, pertb=None)[source]¶

Simulate time series on a network from the Lotka-Volterra model.

The Lotka-Volterra model was designed to describe dynamics of species abundances in an ecosystem. Species \(i\)’s abundance change per time is \(\frac{d X_i}{d t} = r_i X_i \left(1 - \frac{X_i}{K_i} + \sum_{j \neq i} W_{ij} \frac{X_j}{K_i}\right)\) where \(r_i\) and \(K_i\) are the growth rate and the carrying capacity of species \(i\) respectively, and \(W_{ij}\) are the relative interaction strength of species \(j\) on \(i\).

The results dictionary also stores the ground truth network as ‘ground_truth’ and the intermediate time steps as ‘time_steps’.

Parameters

G (nx.Graph): Underlying ground-truth network of simulated time series which has \(N\) nodes.
L (int): Length of time series.
init (np.ndarray): Length-\(N\) 1D array of nodes’ initial condition. If not specified an initial condition is unifromly generated from 0 to the nodes’ carrying capacity.
gr (np.ndarray): Length-\(N\) 1D array of nodes’ growth rate. If not specified, default to 1 for all nodes.
cap (np.ndarray): Length-\(N\) 1D array of nodes’ carrying capacity. If not specified, default to 1 for all nodes.
inter (np.ndarray): \(N \times N\) array of interaction weights between nodes. If not specified, default to a zero-diagonal matrix whose [i, j] entry is \(\frac{sign(j - i)}{N - 1}\).
dt (float or np.ndarray): Sizes of time steps when simulating the continuous-time dynamics.
stochastic (bool): Whether to simulate the stochastic or deterministic dynamics.
pertb (np.ndarray): Length-\(N\) 1D array of perturbation magnitude of nodes’ growth. If not specified, default to 0.01 for all nodes.

Returns

TS (np.ndarray): \(N \times L\) array of L observations on \(N\) nodes.

Notes

The deterministic dynamics is simulated through the forth-order Runge-Kutta method, and the stochastic one is simulated through multiplicative noise with the Euler-Maruyama method.

The ground-truth network, time steps and the time series can be found in results[‘ground-truth’], reuslts[‘time_steps’] and results[‘time_series’] respectively.

class netrd.dynamics.IsingGlauber[source]¶

Ising-Glauber model.

simulate(G, L, init=None, beta=2)[source]¶

Simulate time series on a network from the Ising-Glauber model.

In the Ising-Glauber model, each node has a binary state. At every time step, nodes switch their state with certain probability. For inactive nodes, this probability is \(1 / (1 + e^{\beta (k - 2m) / k})\) where \(\beta\) is a parameter tuning the likelihood of switching state, \(k\) is degree of the node and \(m\) is the number of its active neighbors; for active nodes the switch-state probability is \(1 - 1 / (1 + e^{\beta (k - 2m) / k})\) instead.

The results dictionary also stores the ground truth network as ‘ground_truth’.

Parameters

G (nx.Graph): Underlying ground-truth network of simulated time series which has \(N\) nodes.
L (int): Length of time series.
init (np.ndarray): Length-\(N\) 1D array of nodes’ initial condition, which must have binary value (0 or 1).
beta (float): Inverse temperature tuning the likelihood that a node switches its state. Default to \(2\).

Returns

TS (np.ndarray): \(N \times L\) array of \(L\) observations on \(N\) nodes.

class netrd.dynamics.BranchingModel[source]¶

A sand-pile-like branching process.

simulate(G, L, initial_fraction=0.1, m=0.9975, target_Ahat=0.2, distribution_type='unif', scale=0.95, noise=True)[source]¶

Simulate a (sand-pile-like) branching process dynamics .

The results dictionary also stores the ground truth network as ‘ground_truth’.

Parameters

G (nx.Graph): directed or undirected ground truth graph
L (int): desired length of time series
initial_fraction (float): fraction of nodes that start as active
m (float): branching ratio of the dynamical process. \(m=1.0\) means the system will be at criticality
target_Ahat (float): desired average activity. This will ensure the process does not reach a stationary state and will always have some external drive.
num_edges (int): the length of the cache, which should correspond to the combination of all possible activity over the simulation.
distribution_type (str): string describing which type of random numbers
scale (float): scale for how likely nodes are to topple
noise (bool): add nonzero values to the time series

Returns

TS (np.ndarray): an \(N \times L\) time series

References

1: Levina, Anna, and Viola Priesemann. “Subsampling scaling.” Nature communications 8 (2017) 15140. https://www.nature.com/articles/ncomms15140

class netrd.dynamics.VoterModel[source]¶

Voter dynamics.

simulate(G, L, noise=None)[source]¶

Simulate voter-model-style dynamics on a network.

Nodes are randomly assigned a state in \(\{-1, 1\}\); at each time step all nodes asynchronously update by choosing their new state uniformly from their neighbors. Generates an \(N \times L\) time series.

The results dictionary also stores the ground truth network as ‘ground_truth’.

Parameters

G (nx.Graph): the input (ground-truth) graph with N nodes.
L (int): the length of the desired time series.
noise (float, str or None): if noise is present, with this probability a node’s state will be randomly redrawn from \(\{-1, 1\}\) independent of its neighbors’ states. If ‘automatic’, set noise to \(1/N\).

Returns

TS (np.ndarray): an \(N \times L\) array of synthetic time series data.

class netrd.dynamics.SISModel[source]¶

Susceptible-Infected-Susceptible dynamical process.

simulate(G, L, num_seeds=1, beta=None, mu=None)[source]¶

Simulate SIS model dynamics on a network.

The results dictionary also stores the ground truth network as ‘ground_truth’.

Parameters

G (nx.Graph): the input (ground-truth) graph with \(N\) nodes.
L (int): the length of the desired time series.
num_seeds (int): the number of initially infected nodes.
beta (float): the infection rate for the SIS process.
mu (float): the recovery rate for the SIS process.

Returns

TS (np.ndarray): an \(N \times L\) array of synthetic time series data.